Update Pages

Update Pages

Blog posts, documentation, and static pages are written in Markdown. This guide explains how to create and edit each type.

If you’re using Decap CMS, you can edit these files from the browser. If you’re using Code Only, edit them directly in your code editor.

What Is Markdown?

Markdown is a plain text format with simple syntax for formatting. It’s designed to be readable as-is.

# Heading 1
## Heading 2

Regular paragraph text.

- List item
- Another item

**Bold text** and *italic text*.

[Link text](https://example.com)

`inline code`

Every Markdown file starts with frontmatter — metadata between --- lines:

---
title: My Page
description: A short description.
---

# Content starts here

Frontmatter tells Astro how to render the page.

Blog Posts

Location: src/content/blog/

Each blog post is a .md file. The filename becomes the URL slug.

Example: src/content/blog/astro-themes-2026.md → /blog/astro-themes-2026/

Frontmatter

---
title: "Astro Themes in 2026"
description: "A review of premium Astro themes."
date: 2026-10-15
tags: [astro, themes, review]
image: https://images.unsplash.com/photo-xxx
imageAlt: "A laptop with code on screen"
---

Required fields:

• title — post title

Optional fields:

• description — SEO description (150–160 chars)
• date — publish date (YYYY-MM-DD)
• tags — array of tags
• image — featured image URL
• imageAlt — image alt text for accessibility

Creating a New Post

1. Create a new file: src/content/blog/my-post.md
2. Add frontmatter (see above)
3. Write your content in Markdown
4. Save

The post appears at /blog/my-post/ automatically.

Body Content

Write your post content below the frontmatter:

---
title: "My Post"
date: 2026-10-15
---

# My Post

Opening paragraph.

## Section One

Content here.

## Section Two

More content.

Docs Pages

Location: src/content/docs/

Docs pages use the same Markdown format. The folder structure determines the sidebar navigation.

Example: src/content/docs/getting-started/installation.md → /getting-started/installation/

Frontmatter

---
title: Installation
description: How to install ForgeDocs.
---

Required fields:

• title — page title

Optional fields:

• description — SEO description

Creating a New Doc Page

1. Decide which folder it belongs to (e.g., getting-started)
2. Create a new file: src/content/docs/getting-started/my-page.md
3. Add frontmatter
4. Write content
5. Update the sidebar in astro.config.mjs (if using manual sidebar)

Sidebar Configuration

The sidebar is configured in astro.config.mjs:

sidebar: [
  {
    label: 'Getting Started',
    items: [
      { label: 'Installation', slug: 'getting-started/installation' },
      { label: 'Run Project', slug: 'getting-started/run-project' },
    ],
  },
],

Or use autogenerate:

sidebar: [
  {
    label: 'Getting Started',
    autogenerate: { directory: 'getting-started' },
  },
],

With autogenerate, all .md files in the folder appear in the sidebar automatically — sorted alphabetically.

Ordering files: Prefix filenames with numbers:

getting-started/
├── 01-installation.md
├── 02-run-project.md
└── 03-first-setup.md

Static Pages

Location: src/content/pages/

Static pages are for About, FAQ, Terms, Privacy, and similar. They use a dynamic route (/pages/[page].astro) to render at /{filename}.

Example: src/content/pages/about.md → /about/

Frontmatter

---
title: About
description: About ForgeDocs.
image: https://images.unsplash.com/photo-xxx
imageAlt: "Team collaborating"
layoutType: default
showInNav: true
navOrder: 1
updated: 2026-10-15
---

Required fields:

• title

Optional fields:

• description — SEO description
• image — hero image
• imageAlt — image alt text
• layoutType — default, faq, legal, or contact
• showInNav — show in navigation
• navOrder — order in nav (lower = first)
• updated — last updated date

Layout Types

default — Standard page layout with hero and content

faq — Accordion-style FAQ layout

legal — Narrower content width for legal text

contact — Contact page layout with form

Example: Creating an About Page

Create src/content/pages/about.md:

---
title: About
description: Learn about ForgeDocs and our mission.
image: https://images.unsplash.com/photo-1522071820081
imageAlt: "Team collaborating"
layoutType: default
showInNav: true
navOrder: 1
---

# About ForgeDocs

ForgeDocs is an all-in-one Astro theme for founders.

## Our Mission

To help developers ship documentation sites faster.

The page appears at /about/.

Example: Creating a FAQ Page

Create src/content/pages/faq.md:

---
title: FAQ
description: Frequently asked questions.
layoutType: faq
showInNav: true
navOrder: 2
---

## What is ForgeDocs?

An all-in-one Astro theme.

## How much does it cost?

$79 for Code Only, $129 with Decap CMS.

The FAQ layout renders each ## heading as an accordion item.

Example: Creating a Terms Page

Create src/content/pages/terms.md:

---
title: Terms & Conditions
description: Terms of use for ForgeDocs.
layoutType: legal
showInNav: false
updated: 2026-10-15
---

## License

When you purchase ForgeDocs, you receive...

## Refund Policy

All sales are final...

The legal layout uses a narrower width for better readability.

Markdown Syntax Reference

Headings

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Use one # per page. Use ## for main sections, ### for subsections.

Text Formatting

**Bold text**
*Italic text*
~~Strikethrough~~
`Inline code`

Lists

- Item one
- Item two
  - Nested item

1. First
2. Second
3. Third

Links

[Link text](https://example.com)
[Internal link](/blog)
[Email](mailto:hello@example.com)

Images

![Alt text](https://example.com/image.jpg)

Code Blocks

```bash
npm install
npm run dev
```

Specify the language after the backticks for syntax highlighting.

Blockquotes

> This is a blockquote.
> It can span multiple lines.

Tables

| Column 1 | Column 2 |
|---|---|
| Value 1 | Value 2 |
| Value 3 | Value 4 |

Horizontal Rule

---

Callouts (MDX only)

For MDX files, use Starlight’s callout components:

:::note
This is a note.
:::

:::tip
This is a tip.
:::

:::caution
This is a caution.
:::

:::danger
This is a danger warning.
:::

MDX vs Markdown

Markdown (.md) — Standard Markdown. No imports, no components.

MDX (.mdx) — Markdown with JSX. You can import components:

---
title: My Page
---

import MyComponent from '../../components/MyComponent.astro';

# My Page

<MyComponent />

Regular Markdown continues here.

Use MDX when you need to embed components. Use Markdown for everything else.

Special Frontmatter

Starlight Docs

Starlight supports additional frontmatter:

---
title: My Page
description: A description
sidebar:
  order: 1        # Order in sidebar
  label: Custom   # Override sidebar label
  hidden: false   # Hide from sidebar
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 3
---

Static Pages

Static pages use ForgeDocs’ custom frontmatter:

---
title: About
layoutType: default
showInNav: true
navOrder: 1
updated: 2026-10-15
---

Common Issues

Page shows 404

• Check the filename matches the URL
• Verify the frontmatter has a title
• Restart the dev server

Sidebar doesn’t update

• If using manual sidebar, update astro.config.mjs
• If using autogenerate, check the file is in the right folder
• Restart the dev server

Markdown doesn’t render

• Check for unclosed code fences
• Verify frontmatter is properly delimited with ---
• Look for stray characters before the opening ---

Images don’t load

• Use full URLs: https://example.com/image.jpg
• Or paths from public/: /images/my-image.jpg
• Check the file exists

Special characters break the page

• Escape quotes in frontmatter: "He said \"hello\""
• Avoid special YAML characters in unquoted values: :, {, [, ,

Best Practices

1. Write descriptions for every page. They’re used for SEO and social sharing.

2. Use meaningful filenames. They become URLs. Use lowercase, hyphens instead of spaces.

3. Keep headings hierarchical. Don’t skip from ## to ####.

4. Add alt text to every image. Screen readers and search engines need it.

5. Keep posts focused. One post, one topic.

6. Link to related content. Internal links help readers and SEO.

7. Use code fences with language tags. bash, js, json, md.

8. Preview before publishing. Run npm run dev and check your changes.

What’s Next

Learn about advanced topics:

→ Others

Need Help?

If you’re stuck:

• Check the FAQ
• Email creativebydre@gmail.com
• For custom work, hire me on Fiverr