Static Pages

What Are Static Pages?

Static pages are standalone pages that are not part of the documentation and not part of the blog. They are simple, single-file pages you create for things like:

• About
• Terms of Service
• Privacy Policy
• Refund Policy
• Contact
• FAQ

Each one lives as a single .md or .astro file directly inside src/pages/. That means its URL is derived from the filename.

---

Where They Live

src/pages/
├── contact.md          → /contact/
├── about.md            → /about/
├── terms.md            → /terms/
├── privacy.md          → /privacy/
└── ...

Anything placed directly in src/pages/ becomes a route at the root of your site. This is Astro’s file-based routing.

File	URL
src/pages/about.md	/about/
src/pages/terms.md	/terms/
src/pages/privacy.md	/privacy/

---

The Anatomy of a Static Page

Every static page has two parts:

1. Frontmatter (between --- markers at the top)
2. Body content (everything below the frontmatter)

Example — src/pages/about.md:

---
layout: ../design/page.astro
title: About Astro Docus
description: Astro Docus is a documentation and blog template built with Astro and Starlight. JSON driven content, MDX support and SEO ready.
image: /src/assets/astrojs.svg
---

Astro Docus is a premium Astro template designed for documentation websites, technical blogs and product landing pages.

Frontmatter fields

Field	Purpose
layout	Path to the layout component that wraps this page
title	Page title (browser tab + SEO)
description	Meta description used by search engines
image	Social preview image (Open Graph)

Body

Everything after the frontmatter is standard Markdown. You can use:

• Headings (##, ###)
• Bold (**text**)
• Italic (*text*)
• Lists
• Links ([text](url))
• Images (![alt](path))
• Code blocks
• Blockquotes
• Tables

---

The Layout

The layout field tells Astro which wrapper to use. The template ships with several layouts in src/design/:

Layout	Use for
../design/page.astro	Generic pages (About, Terms, etc.)
../design/contact.astro	Contact page with form
../design/base.astro	Minimal wrapper
../design/default.astro	Full page with navbar + footer
../design/about.astro	About-style layout

For most custom pages, use page.astro:

layout: ../design/page.astro

Note: The path starts with ../ because the page lives in src/pages/ and the layout lives in src/design/.

---

CRUD — Create, Read, Update, Delete

The template makes it easy to manage static pages using the four basic operations.

Create — Adding a New Page

1. Open src/pages/ in VS Code.
2. Right-click the pages folder → New File.
3. Name it with .md extension: about.md, terms.md, etc.
4. Add the frontmatter and body:

---
layout: ../design/page.astro
title: About Us
description: Learn more about our team and mission.
image: /src/assets/astrojs.svg
---

## Our Story

We build documentation templates for developers.

## Our Mission

To make documentation beautiful and easy to maintain.

5. Save the file.
6. Visit /about/ in your browser. The page is live.

That’s it. No configuration needed. No sidebar entry required unless you want one.

Read — Viewing a Page

To read (view) a page you’ve created:

1. Start the dev server: npm run dev
2. Open http://localhost:4321/your-page/

The URL is the filename without the .md extension.

Update — Editing a Page

To update a page:

1. Open the .md file in src/pages/.
2. Edit the frontmatter or body.
3. Save.

The dev server reloads automatically.

Common updates:

• Change title to update the browser tab
• Change description to update SEO
• Add new sections with ## headings
• Insert images with ![alt](/path/to/image.png)

Delete — Removing a Page

To delete a page:

1. In VS Code’s file explorer, right-click the .md file.
2. Click Delete.
3. Confirm.

The URL /your-page/ stops working immediately.

Warning: If the page is linked from your navbar or footer, remember to remove the link from src/data/configuration/home/homepage.json as well.

---

Adding Links to Your New Page

Creating the page is only half the job. To make it findable, add it to the navbar or footer.

Add to navbar

1. Open src/data/configuration/home/homepage.json.
2. Find the navbar array.
3. Add a new item:

{ "nav": "About", "link": "/about/" }

4. Save. The link appears in the navbar on every page.

Add to footer

1. In the same file, find a footer column — e.g., footer1_nav.
2. Add:

{ "nav": "About", "link": "/about/" }

3. Save. The link appears in the footer.

Add to docs sidebar (optional)

If you want the page to appear in the documentation sidebar, add it to astro.config.mjs:

{
  label: 'About',
  link: '/about/',
}

See Configuration for the full sidebar reference.

---

Markdown Cheatsheet

A quick reference for what you can write inside a static page.

Headings

## Section Title
### Subsection
#### Smaller heading

Text

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

Lists

- Item one
- Item two
  - Nested item

1. First
2. Second
3. Third

Links and images

[Link text](https://example.com)
![Alt text](/src/assets/image.png)

Code blocks

```js
const message = 'Hello world';
```

Blockquotes

> This is a quote.

Tables

| Column A | Column B |
|----------|----------|
| Value 1  | Value 2  |

---

Using MDX Instead of Markdown

If you need to embed components inside a static page, use .mdx instead of .md:

---
layout: ../design/page.astro
title: Interactive Page
description: A page with embedded components.
---

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

## Welcome

<MyComponent />

The routing works the same. src/pages/interactive.mdx becomes /interactive/.

---

Rules for Static Pages

1. One file = one URL. The filename determines the route.
2. Every page needs frontmatter. At minimum, include layout and title.
3. Use page.astro as default layout unless you have a specific reason.
4. Do not name files with spaces. Use about-us.md, not about us.md.
5. Do not use special characters in filenames — stick to lowercase and hyphens.
6. Remember to link new pages — otherwise no one will find them.

---

Common Mistakes

Mistake	Result	Fix
Missing layout in frontmatter	Page renders without styling	Add layout: ../design/page.astro
Wrong path to layout	Build error	Check the ../design/ prefix
Filename with spaces	URL breaks	Rename with hyphens
Forgetting to add link to navbar	Page is orphaned	Update homepage.json
Using .md when embedding components	Component syntax ignored	Rename to .mdx

---

Quick Recap

src/pages/
├── about.md      → /about/
├── terms.md      → /terms/
├── privacy.md    → /privacy/
└── faq.md        → /faq/

CRUD workflow:

Action	How
Create	New .md file in src/pages/ + frontmatter
Read	Visit /filename/ in browser
Update	Edit the .md file and save
Delete	Remove the file

Frontmatter minimum:

---
layout: ../design/page.astro
title: Page Title
description: Page description
image: /src/assets/astrojs.svg
---

• File-based routing — filename = URL.
• Markdown body — write naturally.
• Link it in homepage.json to make it findable.
• MDX option — use .mdx if you need components.

👉 Next: docs/data/index-page.md — how JSON powers documentation landing pages.