Docs + Blog + Landing in One Astro Project — Here's How

The Three-Site Problem

Every product team eventually ends up with three websites.

There’s the marketing site — pretty, designed by a real designer, lives on the main domain, tells a story, has a pricing page.

There’s the docs site — usually at docs.yourdomain.com or yourdomain.com/docs, built with whatever framework the docs person was excited about that year.

And there’s the blog — often WordPress, sometimes a Ghost instance, occasionally just a folder full of Markdown that nobody maintains.

Three sites. Three build pipelines. Three hosting providers. Three designs that don’t quite match. Three teams of people who all need to know three different systems.

It works. Sort of. But it’s the sort of thing that slowly drains your soul.

Why Three Sites Is a Mistake

Let me count the ways.

Design drift. The landing page gets redesigned. The docs still have the old logo. The blog never had the right font. Now you’ve got three sites that look like they belong to three different companies — except they’re all yours.

Maintenance multiplication. A security patch in one place doesn’t fix the others. A new analytics integration has to be added three times. A brand refresh becomes a three-week project.

Broken cross-links. Someone moves a docs page and forgets to update the link from the blog. Someone renames a blog post and the landing page CTA now 404s. Nobody notices for a month.

Context switching. The docs person doesn’t know how the marketing site works. The marketing person doesn’t want to touch the docs config. The blog person is on vacation.

And the killer — users can’t move between them. Someone reads your blog post, wants to see the docs, has to mentally switch contexts. Someone reads the docs, wants to see pricing, gets bounced to a completely different site.

It’s exhausting. And it’s unnecessary.

One Project, Three Purposes

Here’s the radical idea: what if docs, blog, and landing page all lived in the same project?

Same build. Same deploy. Same design system. Same navigation. Same everything.

This is what Astro makes genuinely easy — and it’s why Astro Docus exists.

Let me show you how it works.

The Architecture

One Astro project. Three different content types, all sharing one foundation.

src/
├── content/docs/       → documentation pages
├── pages/blog/         → blog posts
├── data/               → JSON for landing page
├── design/             → shared layouts
├── widget/             → shared components
└── styles/             → shared CSS

The landing page lives at /. The docs live at /getstart/, /cms/, /hosting/, and so on. The blog lives at /blog/. The pricing page lives at /plan/.

But they all share:

• The same navbar — defined once in JSON
• The same footer — also JSON
• The same color tokens — one CSS file
• The same design language — same components, same spacing, same typography
• The same build pipeline — one npm run build produces everything
• The same deploy — one push, everything goes live

The user never notices they’ve crossed a boundary. It just feels like one site — because it is one site.

Why This Works So Well

Content Types Can Share a Collection

Astro’s content collections handle both docs and blog posts. The blog uses an extended schema (with pubDate, tags, categories), but the files live in the same content pipeline.

This means:

• One config.ts file defines the schema for everything
• One build processes all content
• One search index covers docs and blog

No duplication. No second build step. No “wait, which folder does this go in?”

Navigation Is Data, Not Code

The navbar and footer for all three sections come from JSON files. Changing a menu item in the JSON updates the navbar everywhere — docs, blog, landing, pricing. All at once.

This isn’t just convenient. It’s correct. A navbar is data. Treating it as data means treating it as something that can change without a developer.

The Design System Is Actually Shared

Same fonts. Same spacing scale. Same button styles. Same color variables.

The blog doesn’t look like a different site. The docs don’t feel bolted on. The landing page doesn’t clash with everything else.

For users, this feels professional. For developers, it means changing a CSS variable in one place updates the entire site.

The Developer Experience

Here’s what the workflow actually looks like.

Writing a blog post: create a new .md file in src/pages/blog/, add frontmatter, write content. Astro picks it up, adds it to the blog index, generates the post page, updates the RSS feed, and creates tag and category archives. One file. Everything else is automatic.

Adding a docs page: create a new .md or .mdx file in src/content/docs/, write content. The sidebar updates (if it’s autogenerated), search indexes it, and it’s live.

Editing the landing page: open a JSON file in src/data/, change the text, save. The homepage updates. No code touched, no rebuild needed during development.

Adding a navbar item: open src/data/configuration/home/homepage.json, add one line, save. The navbar changes everywhere.

No context switching. No “which project was this in?” moment. No “wait, does this file go in the docs repo or the blog repo?”

The Hosting Story

One build. One output folder (dist/). One deploy.

You can put the whole thing on:

• Cloudflare Pages — free, fast, automatic Git deploys
• Vercel — free tier, framework detection, preview URLs
• Netlify — free tier, drag-and-drop deploy option
• Firebase Hosting — Google infrastructure
• Any static host, any VPS, any cPanel

The docs, blog, and landing page all deploy together. One URL. One SSL certificate. One thing to maintain.

Compare that to running WordPress, Docusaurus, and a Framer site across three different hosts — with three different DNS records, three different SSL renewals, and three different places things can break.

When You Might Not Want This

I’m going to be honest about where this approach has limits.

If your marketing team needs a specific CMS. Marketing folks often have strong opinions about their tools — HubSpot, Webflow, Contentful. If they’re already happy with those, forcing them onto a JSON-driven landing page might not go over well.

If your docs team needs versioning. Some products ship multiple versions of docs simultaneously. Starlight versioning is in progress but not mature yet.

If you need different CDN strategies. Landing pages and docs have different traffic patterns. If you’re serving millions of requests per day, you might want separate CDN configs. This matters for scale, not for most projects.

If your team is already distributed across tools. If the docs team uses Docusaurus, the marketing team uses Webflow, and the blog team uses Ghost, and everyone is happy — the cost of migration might not be worth the benefit.

For everyone else, one project is better.

The Alternative Approach

Let me at least acknowledge the standard answer: build three sites.

It works. Lots of companies do it. There’s nothing wrong with it.

But here’s the thing — the three-site approach doesn’t save time. It just distributes the pain. Instead of one complex project, you have three simple ones. Except simple things multiply.

Three sites = three security updates. Three hosts = three places to forget to update. Three designs = three things to keep in sync. Three deploys = three times things can fail.

The one-project approach centralizes the complexity. You have one complex thing instead of three simple things. And complex things that are designed well are easier to maintain than simple things that are multiplied.

What to Do Next

If you want to see this approach in action, Astro Docus is a working example — it’s the site you’re reading right now. The docs are in the docs section. The blog is here. The landing page is at the root. The pricing page is at /plan/.

All one project. All one deploy. All free to host.

If you want to build your own, start with Astro, add Starlight, and organize your content. The rest is details.

The three-site era is over. Your docs, blog, and landing page belong together.

Astro Docus ships with all of this wired up — docs, blog, landing page, pricing page, JSON-driven content, and deployment ready. If you want to skip the setup, grab it on Gumroad.

Share This Article