This guide walks you through creating and publishing pages and articles. It covers the fields you need to fill in, how to write content in markdown, how to handle images, and how to preview and publish your work.
Who This Is For
- Editors creating or updating site pages (about, services, legal, etc.)
- Editors writing blog posts, news articles, or case studies
You do not need to know Astro or any programming language. If you can edit a text file and write markdown, you have everything you need.
How Content Works
All site content lives in the src/content/ directory as markdown files:
| Content type | Directory | URL pattern | Example URL |
|---|---|---|---|
| Pages | src/content/pages/ | /{slug}/ | /about/ |
| Articles | src/content/articles/ | /articles/{file-slug}/ | /articles/case-study-acme/ |
Each file has two parts: a frontmatter block at the top (metadata between --- lines) and the body (your written content in markdown).
For the full technical reference on content collections, schemas, and all available fields, see Content Collections (DOC-00005).
Creating a Page
To create a new page, add a markdown file in src/content/pages/. The filename determines the URL unless you set a slug override.
Page frontmatter
---
title: About Us
description: Learn more about our team and mission.
slug: /about
draft: false
datePublished: 2026-03-07
category: company
tags:
- team
- mission
---Field reference for editors
| Field | Required | What it does |
|---|---|---|
title | Yes | Page title. Appears as the main heading and in browser tabs. |
description | Yes | Short summary (1-2 sentences). Used in search results and previews. |
slug | No | Overrides the URL path derived from the filename. |
draft | No | Set to true to hide from the live site. Default: false. |
datePublished | No | Publication date in YYYY-MM-DD format. |
dateModified | No | Last edit date in YYYY-MM-DD format. |
category | No | Primary category for grouping. |
tags | No | List of tags for filtering and related content. |
For advanced fields like ogImage, canonical, and heroTitle, see Content Collections (DOC-00005) and SEO and Analytics (DOC-00022).
Creating an Article
To create a new article, add a markdown file in src/content/articles/. Name the file with a descriptive slug — for example, how-we-redesigned-our-homepage.md.
Article frontmatter
---
title: How We Redesigned Our Homepage
description: A look at the process behind our recent homepage redesign.
draft: false
datePublished: 2026-03-07
category: design
tags:
- case-study
- design
---Articles use the same fields as pages. The only difference is the URL pattern: articles are served under /articles/.
Writing Content in Markdown
After the frontmatter block, write your content in standard markdown. Here are the basics.
Headings
Start your body headings at ## (the page title is automatically rendered as the top-level heading from the frontmatter title field — do not repeat it).
## Section Title
### Subsection Title
#### Sub-subsection TitleText formatting
This is **bold text** and this is _italic text_.Links
[Link text](https://example.com)
[Link to another page](/about/)Always use explicit link syntax when you want a clickable link. Do not rely on bare URLs or domain names — while GFM autolinking may convert them, the result is unpredictable.
If you mention a domain name or URL as plain text (not intended as a clickable link), wrap it in backticks to prevent automatic conversion:
We migrated from `oldsite.com` to our new domain.
The `www` subdomain redirects to the root domain.Without backticks, text like example.com or www.example.com will be automatically converted into clickable links by the markdown processor.
Lists
Bulleted lists:
- First item
- Second item
- Third itemNumbered lists:
1. First step
2. Second step
3. Third stepCode
Inline code uses backticks: `like this`.
Code blocks use triple backticks with a language identifier:
```html
<p>Hello world</p>
```Blockquotes
> This is a blockquote. Use it for callouts or quoted text.Image Handling
Where images go
Place images in src/site/assets/. Reference them from your markdown or use the Astro <Image> component in .astro files.
Alt text requirements
Every image must have meaningful alt text that describes what the image shows. Alt text is essential for accessibility — screen readers read it aloud for users who cannot see the image.
Good alt text:
Bad alt text (avoid these patterns):
— “screenshot” says nothing about the content— “image” is meaningless— empty alt text makes the image invisible to screen readers
If an image is purely decorative (adds no information), use empty alt text: . This tells screen readers to skip it.
Draft Workflow
The draft field controls whether content appears on the live site.
How drafts work
draft: true— the page is excluded from the production build, sitemap, and search indexing. It will not appear on the live site.draft: false(or omitted) — the page is published and visible to everyone.
Previewing draft content
Draft pages are visible on the local development server. To preview:
- Open a terminal in the project directory.
- Run:
npm run dev- Open the URL shown in the terminal (typically
http://localhost:4321/). - Navigate to your draft page. It will render normally on the dev server even though it is excluded from production.
This lets you review content, check formatting, and verify images before publishing.
Publishing Checklist
Before setting draft: false (or removing the draft field), verify the following:
- Title is filled in and accurately describes the page
- Description is filled in (1-2 clear sentences)
- Content is proofread — no typos, broken sentences, or placeholder text
- All images have meaningful alt text — not “screenshot”, “image”, or empty
- Dates are set —
datePublishedreflects the intended publication date - Preview looks correct — run
npm run devand check the page renders as expected, images load, and links work - Headings start at
##— the page title comes from frontmatter, not from a#heading in the body