Blog Introduction
Blog System
Section titled “Blog System”A complete blog with listing, post detail, tags, categories, and RSS — all from Markdown files.
Blog — Introduction
Section titled “Blog — Introduction”What Is This Blog?
Section titled “What Is This Blog?”This blog is not the default Starlight documentation layout. It is a custom-built blog system designed specifically for Astro Docus — a complete extension that transforms a documentation site into a multi-purpose platform.
The core idea is simple: a documentation site should not be limited to only documentation. Modern projects need:
- Documentation — guides, references, API notes
- Blog — announcements, tutorials, changelogs
- Landing pages — marketing, onboarding, feature overviews
- Pricing pages — plans, tiers, purchase options
Astro Docus gives you all of these in one project, with one build, and one deployment.
Why This Blog Exists
Section titled “Why This Blog Exists”Standard Starlight sites are built for documentation only. Adding a blog usually means:
- Installing a third-party plugin
- Learning a new configuration surface
- Mixing two different content systems
- Dealing with plugin-specific frontmatter rules
This blog avoids all of that.
It lives inside the same docs collection as your documentation. Every blog post is a Markdown or MDX file. It uses the same content system, the same build pipeline, and the same deployment target.
No separate blog plugin. No separate content folder. No conflicting configuration.
What This Blog Includes
Section titled “What This Blog Includes”The custom blog system ships with a complete feature set for real-world use:
| Feature | Purpose |
|---|---|
| Post listing | Paginated blog index at /blog/ |
| Post detail | Individual post pages |
| Tags | Tag archives at /tags/[tag]/ |
| Categories | Category archives at /categories/[category]/ |
| RSS feed | Feed at /rss.xml |
| Pagination | Blog list, tag pages, category pages |
| SEO | Meta tags, Open Graph, canonical URLs |
| Markdown & MDX | Write posts in either format |
All of these are rendered at build time as static HTML. No runtime, no server, no database.
The Content Pipeline
Section titled “The Content Pipeline”Blog posts live inside the same content collection as documentation:
src/content/docs/├── blog/│ ├── post-one.md│ ├── post-two.mdx│ └── ...├── getstart/├── cms/└── ...Every file with a date field in its frontmatter is treated as a blog post. Files without a date field are treated as documentation pages.
This means:
- One content system — no second collection to maintain
- One schema — extended to support blog fields like
date,tags, andcategories - One build — documentation and blog generate together
The schema validation is handled by extending Starlight’s docsSchema() with blog-specific fields. If a file has a date, it is validated as a blog post. If it does not, it is validated as a documentation page .
How It Fits Into Astro Docus
Section titled “How It Fits Into Astro Docus”Astro Docus is designed for multi-purpose documentation sites. The blog is one piece of that puzzle.
| Section | Powered by | URL |
|---|---|---|
| Documentation | Starlight + MDX | /getstart/, /cms/, etc. |
| Blog | Custom blog system | /blog/ |
| Landing | JSON + widgets | / |
| Pricing | JSON + MDX | /pricing/ |
| Static pages | Markdown + layouts | /about/, /contact/, etc. |
Everything shares the same navbar, the same footer, and the same design tokens. The blog does not feel like an add-on — it feels like part of the site.
When to Use the Blog
Section titled “When to Use the Blog”Use the blog when you need to publish:
- Product updates — new features, version releases
- Tutorials — step-by-step guides that do not belong in the reference docs
- Announcements — events, partnerships, milestones
- Thought pieces — architecture decisions, lessons learned
- Changelogs — structured release notes
The blog is optional. If you only need documentation, you can ignore the blog entirely. Nothing breaks.
But if you want a complete documentation platform — docs + blog + landing + pricing — the blog is already wired in.
What Comes Next
Section titled “What Comes Next”The blog system has several sub-topics. They will be documented one by one:
- Blog Structure — where posts live, how folders are organized
- Blog Frontmatter — title, date, tags, categories, description
- Blog Listing — how the
/blog/page is built - Blog Post Detail — how individual posts render
- Tags — tag archives and tag navigation
- Categories — category archives
- RSS Feed — how the feed is generated
- Pagination — how pages are split
- Blog Configuration — customizing the blog navbar and metadata
Each topic gets its own page under docs/blog/.
Quick Recap
Section titled “Quick Recap”Astro Docus = Documentation + Blog + Landing + Pricing
Blog:├── Lives inside src/content/docs/blog/├── Uses the same docs collection├── Extended schema with date, tags, categories├── Renders at /blog/, /tags/, /categories/├── Generates RSS at /rss.xml├── Static output — no runtime└── Optional — safe to ignore if not neededThe blog is not a plugin. It is not a separate app. It is a first-class part of Astro Docus, designed to make your documentation site complete.