Static Docs Pages

What Are Static Docs Pages?

A static docs page is a standalone MDX file placed directly inside src/content/docs/. It becomes a page in your documentation site — with the Starlight layout, sidebar, and navigation — but is not part of any folder group.

Common uses:

Welcome page
Landing page for a section
Single-topic page (FAQ, Changelog, Roadmap)
Thank-you pages

Every file you drop into src/content/docs/ becomes a route.

File	URL
`src/content/docs/welcome.mdx`	`/welcome/`
`src/content/docs/changelog.mdx`	`/changelog/`
`src/content/docs/faq.mdx`	`/faq/`

Where They Live

src/content/docs/
├── index.mdx
├── welcome.mdx       ← static docs page
├── changelog.mdx     ← static docs page
├── getstart/         ← folder group
├── cms/              ← folder group
└── ...

Files at the root of docs/ become top-level URLs. Files inside subfolders become nested URLs.

MDX Only — Not Markdown

For these standalone pages, use the .mdx extension, not .md.

Why? MDX supports:

JSX components
Imports
Astro expressions like {frontmatter.title}
Dynamic content

Plain .md files work too, but MDX is the recommended format for docs pages because it lets you import widgets, cards, and interactive elements.

The Anatomy of a Static Docs Page

Every static docs page has two parts:

Frontmatter (between --- markers)
Body (Markdown + optional MDX)

Example — `src/content/docs/welcome.mdx`

---
title: Tester
description: Get Astro Docus premium template for only $29. Starlight Astro JS documentation template with blog, landing, pricing. JSON driven, MDX ready, SEO optimized. Buy now on Gumroad.
template: splash
tableOfContents: false
prev: false
next: false
---

Bro

This renders at /welcome/.

Frontmatter Fields

Frontmatter controls how the page behaves inside Starlight. Each field affects the layout or navigation.

Field	Purpose
`title`	Page title — shown in sidebar, browser tab, and page header
`description`	Meta description for SEO and social previews
`template`	Layout variant — `doc` (default) or `splash`
`tableOfContents`	Show/hide the right-side TOC
`prev`	Show/hide the “Previous page” link at the bottom
`next`	Show/hide the “Next page” link at the bottom

`template`

Value	Result
`doc`	Standard documentation layout with sidebar (default)
`splash`	Wide, centered layout — great for welcome pages

Use splash when you want the page to feel like a landing page rather than a doc.

`tableOfContents`

Value	Result
`true` (default)	Show the right-side heading navigation
`false`	Hide it

Set to false when the page has no headings, or when you want a cleaner layout.

`prev` and `next`

Value	Result
`true` (default)	Show the previous/next navigation links
`false`	Hide them

Set both to false for pages that are standalone — like a welcome page or a thank-you page.

Creating a New Static Docs Page

Step 1 — Create the file

In VS Code, right-click src/content/docs/.
Click New File.
Name it with .mdx: welcome.mdx, changelog.mdx, etc.

Step 2 — Add frontmatter

Copy this template and adjust:

---
title: Welcome
description: A short description of what this page is about.
template: splash
tableOfContents: false
prev: false
next: false
---

Your content goes here.

Step 3 — Write the body

Below the frontmatter, write standard Markdown:

---
title: Welcome
description: Welcome to Astro Docus.
template: splash
tableOfContents: false
prev: false
next: false
---

## Welcome to Astro Docus

This is a documentation and blog template built with **Astro** and **Starlight**.

### What's inside

- Documentation system with MDX
- Blog with tags and categories
- Landing page and pricing pages
- JSON-driven content

Ready to get started? Visit the [Get Started](/getstart/) section.

Step 4 — Save and preview

Run npm run dev if it’s not already running.
Open http://localhost:4321/welcome/.
The page renders inside the Starlight layout.

By default, new pages in src/content/docs/ do not appear in the sidebar. You must add them manually.

Open astro.config.mjs and find the sidebar array. Add an entry:

{
  label: 'Welcome',
  link: '/welcome/',
},

Or nest it inside an existing group:

{
  label: 'Get Started',
  items: [
    { label: 'Welcome', link: '/welcome/' },
    { label: 'Installation', link: '/getstart/installation/' },
  ],
},

Save the file. The dev server reloads and the sidebar updates.

Reminder: Starlight does not auto-add root-level pages to the sidebar. Only autogenerate directories do that.

Nested Static Pages

If you want a page to live inside a URL prefix without creating a full folder group, use a subfolder:

src/content/docs/legal/terms.mdx   → /legal/terms/
src/content/docs/legal/privacy.mdx → /legal/privacy/

The folder acts as a URL segment. You can add it to the sidebar as an autogenerated group:

{
  label: 'Legal',
  autogenerate: { directory: 'legal' },
},

Using Components Inside the Page

Because it’s MDX, you can import and use Astro components:

---
title: Welcome
description: Welcome to Astro Docus.
template: splash
tableOfContents: false
prev: false
next: false
---

import Start from '../../widget/index_page/getstart.astro';
import '../../styles/index_page.css';

## Get Started

<Start />

This lets you embed card grids, widgets, or any other component into a docs page.

Difference — Docs Page vs Static Page

There are two types of “static” pages in Astro Docus. They are easy to confuse.

Feature	Docs page	Static page
Location	`src/content/docs/`	`src/pages/`
Extension	`.mdx` (recommended)	`.md` or `.astro`
Layout	Starlight (automatic)	Custom (`page.astro`, `contact.astro`, etc.)
Sidebar	Yes (if added)	No
URL	Based on folder structure	Based on filename
Use for	Documentation	About, Terms, Contact

Docs pages get the Starlight chrome (sidebar, search, theme toggle) automatically. Static pages in src/pages/ do not — they use whatever layout you specify.

Editing and Deleting

Edit

Open the .mdx file.
Change frontmatter or body.
Save.

Delete

Right-click the .mdx file.
Delete.
Remove the sidebar entry from astro.config.mjs.

Rules to Remember

Use .mdx, not .md for standalone docs pages.
Always include title and description in frontmatter.
Use template: splash for welcome or landing pages.
Set prev: false and next: false for standalone pages.
Add to sidebar manually in astro.config.mjs — otherwise it’s invisible.
Respect the folder structure — subfolders create nested URLs.

Common Patterns

Welcome page

---
title: Welcome
description: Welcome to our documentation.
template: splash
tableOfContents: false
prev: false
next: false
---

## Welcome

Start with the [Get Started](/getstart/) guide.

Changelog page

---
title: Changelog
description: All updates to this project.
tableOfContents: false
---

## v1.0.0 — Initial Release

- Documentation system
- Blog with tags
- Landing page

FAQ page

---
title: FAQ
description: Frequently asked questions.
tableOfContents: true
---

## How do I install?

Run `npm install` then `npm run dev`.

## How do I deploy?

See the [Hosting section](/deploy-hosting/).

Thank-you page

---
title: Thank You
description: Your purchase is confirmed.
template: splash
tableOfContents: false
prev: false
next: false
---

## Thank you for your purchase!

Your download link has been sent to your email.

Quick Recap

src/content/docs/welcome.mdx   →  /welcome/
src/content/docs/changelog.mdx →  /changelog/
src/content/docs/faq.mdx       →  /faq/

Frontmatter minimum:

---
title: Page Title
description: Page description
---

For standalone pages, add:

template: splash
tableOfContents: false
prev: false
next: false

Then:

Create the .mdx file.
Write frontmatter.
Write body.
Add to sidebar in astro.config.mjs.
Save and preview.

MDX only — not .md — for docs pages.
Automatic layout — Starlight provides the chrome.
Manual sidebar — you must add it yourself.
Splash template — for welcome and landing-style pages.