How a Viralistic Astro site is organised

Every website Viralistic builds in Astro follows the same structure. Once you know it, you can find your way around any of our sites in minutes. This article explains the folders, the few rules that hold them together, and which file to open for the most common changes. No coding knowledge needed.

The big idea

Content, structure and styling are kept strictly apart:

• Content (text, images, links) lives in markdown and YAML files in src/content.
• Schemas in src/schemas describe exactly which fields each kind of page may have.
• Layouts in src/layouts decide which sections a kind of page shows.
• Blocks and UI components in src/components draw those sections on screen.

Because of this split, you can rewrite every sentence on a page without touching code, and a developer can redesign a section without touching your text.

The folders

astro.config.ts          site URL, name, favicon, languages, fonts
netlify.toml             build settings and redirects
src/
  assets/                images that Astro optimises
  content/
    globals/nl.yaml      site name, navigation, call to action, footer
    pages/               one markdown file per URL
  schemas/               the allowed fields per page type
  layouts/               one layout per page type
  components/
    blocks/              page sections: hero-1, features-1, footer-2
    ui/                  small building blocks: button, card, accordion
  pages/[...page].astro  the single route that renders every page
  styles/global.css      colours, fonts and spacing as design tokens
public/                  files that need a fixed URL, such as PDFs

How a file becomes a page

1. You create a markdown file in src/content/pages. Its path is its URL: pages/webdesign/hosting.md becomes /webdesign/hosting, and pages/index.md becomes the home page.
2. The first line of its frontmatter is type, for example type: service.
3. The single route reads every file and hands it to the layout renderer.
4. The renderer loads src/layouts/service.astro, the layout that matches the type.
5. The layout passes the frontmatter fields to its blocks, and puts the markdown body where the long text belongs.
6. The base layout wraps it all with the header, footer, SEO tags and structured data.

Tip: A file whose name starts with an underscore, such as _draft.md, is skipped by the build. Use this to keep a draft page in the project without publishing it.

The rules that keep it tidy

• One route. There is only one file in src/pages. New pages are new markdown files, never new route files.
• Strict schemas. If a page contains a field its schema does not know, the build stops with an error. This catches typos before they reach your visitors.
• Global data in one place. Navigation, footer links, company details and the main call to action live in src/content/globals/nl.yaml. Components never hard-code them.
• Tokens for styling. Colours, radius and fonts are variables in src/styles/global.css. A rebrand changes the tokens, not hundreds of components.
• Numbered blocks. A different design for a section becomes a new block (hero-2) instead of a switch inside an existing one.

Where to change what

You want to change	Open this
Text on a page	The page’s file in src/content/pages
Menu, footer or main button	src/content/globals/nl.yaml
Page title in Google	title, description or the seo block in the page’s frontmatter
An image	Add it to src/assets and point the page’s frontmatter at it
A downloadable PDF	public/downloads
Brand colours or font	src/styles/global.css and the fonts setting in astro.config.ts
A redirect from an old URL	netlify.toml
A new kind of page	Schema, layout, registration and a content file (a developer task)

Adding a new page type

Most changes are content changes. When a site needs a genuinely new kind of page, such as a job vacancy, a developer always does four things together:

1. Writes a schema in src/schemas/layouts/ with the fields the page needs.
2. Registers it in src/schemas/page.ts under its type name.
3. Builds a layout in src/layouts/ that composes existing or new blocks.
4. Adds the first markdown file with that type.

After that, every new vacancy is just another markdown file.

Next steps

• Edit text and pages
• Images and media
• Edit your site with Claude Code