Blog Index Page

What Is This Page About?

The blog index page — located at /blog/ — is the main listing of all your blog posts. This page is fully configurable from a single JSON file, just like the rest of Astro Docus.

All the content you see on the blog listing page — the title, description, navigation bar, icons, and metadata for tags and categories pages — lives in src/data/configuration/blog/blogpage.json.

This page explains every field in that file, what it controls, and how to customize it for your own blog.

---

Where the File Lives

src/data/
└── configuration/
    └── blog/
        └── blogpage.json

The path is important: configuration/blog/blogpage.json. The configuration/ folder holds shared chrome — navigation, metadata, and settings that appear across multiple pages. The blog/ subfolder scopes this file specifically to the blog section.

---

The Full File

{
  "url": "https://astrodoc.pages.dev/blog",
  "title": "Blog Astro Themes",
  "description": "Update blog Docus Astro JS Starlight Themes template with complete features",
  "categories_page_title": "Categories Astro Themes",
  "categories_page_description": "Update blog Docus Astro JS Starlight Themes template with complete - categories",
  "tags_page_title": "Tags Astro Themes",
  "tags_page_description": "Update blog Docus Astro JS Starlight Themes template with complete features - tagging",
  "icon": "/src/assets/astrojs.svg",
  "image": "/src/assets/newastro.png",
  "navbar": [
    {
      "nav": "Home",
      "icon": "/src/assets/homeblog.svg",
      "link": "/"
    },
    {
      "nav": "Doc",
      "icon": "/src/assets/homedoc.svg",
      "link": "/getstart/"
    },
    {
      "nav": "Blog",
      "icon": "/src/assets/bloggers.svg",
      "link": "/blog/"
    },
    {
      "nav": "Plan",
      "icon": "/src/assets/blogcontact.svg",
      "link": "/pricing/"
    }
  ]
}

---

Field-by-Field Breakdown

Metadata Fields

These fields control the page’s identity, SEO, and social sharing.

Field	Type	Purpose
url	string	The canonical URL of the blog index
title	string	Page title shown in browser tab and SEO
description	string	Meta description for search engines and social previews
icon	string	Small icon used in the blog metadata
image	string	Social preview image (Open Graph)

url — The canonical URL. This is used to build absolute links and to tell search engines which URL is the “official” version of this page. Update it to match your domain.

title — The page title. It appears in the browser tab and as the main heading on the blog index. On the live site, this renders as “Blog Astro Themes”.

description — A one-sentence summary. Used for SEO meta tags and social media previews. It also appears as the subtitle under the title on the blog page.

icon — A small icon associated with the blog. Typically referenced in metadata or as a favicon-style asset.

image — The social preview image. When someone shares your blog index on social media, this image appears in the card.

---

Tags & Categories Page Metadata

The blog has two auxiliary listing pages: one for tags and one for categories. This file contains the titles and descriptions for both.

Field	Type	Controls
categories_page_title	string	Title of /categories/ page
categories_page_description	string	Meta description for /categories/
tags_page_title	string	Title of /tags/ page
tags_page_description	string	Meta description for /tags/

Why separate fields? Because tags and categories are different concepts and may need different descriptions. Keeping them separate lets you write targeted SEO copy for each.

On the live site, the categories page title is “Categories Astro Themes” and the tags page title is “Tags Astro Themes”.

---

The Navbar Array

The navbar array defines the navigation menu specifically for the blog context. Unlike the homepage navbar, this one includes icons for each item.

"navbar": [
  { "nav": "Home", "icon": "/src/assets/homeblog.svg", "link": "/" },
  { "nav": "Doc", "icon": "/src/assets/homedoc.svg", "link": "/getstart/" },
  { "nav": "Blog", "icon": "/src/assets/bloggers.svg", "link": "/blog/" },
  { "nav": "Plan", "icon": "/src/assets/blogcontact.svg", "link": "/pricing/" }
]

Each item has three keys:

Key	Type	Purpose
nav	string	The visible label
icon	string	Path to the icon shown next to the label
link	string	Where the item points

Why icons? The blog is a more visual context than documentation. Icons make the navbar feel lighter and more scannable. On the live site, you can see the icons rendered next to Home, Doc, Blog, and Plan.

The icon key is blog-specific. The homepage navbar in homepage.json does not use icons. This is intentional — each context has its own visual language.

---

How the File Is Consumed

This file is imported by the blog navbar component and by the blog metadata helpers. The pattern is the same as everywhere else in Astro Docus:

blogpage.json  →  blog widgets  →  /blog/ page

The navbar array is looped to render the menu. The metadata fields are read directly for SEO and page titles.

---

Editing Workflow

Change the blog page title

1. Open src/data/configuration/blog/blogpage.json
2. Find "title"
3. Replace the value
4. Save — the title updates on the blog index and in the browser tab

Change the navbar label

1. Find the "navbar" array
2. Locate the item you want to change
3. Update the "nav" value
4. Save

Add a new navbar item

1. Add a new object to the "navbar" array:

{
  "nav": "About",
  "icon": "/src/assets/article.svg",
  "link": "/about/"
}

2. Save — the new item appears in the blog navbar

Swap a navbar icon

1. Place your icon in src/assets/
2. Update the "icon" path for the relevant item
3. Save

Update the social preview image

1. Place your image in src/assets/
2. Update "image"
3. Save — social shares of /blog/ will use the new image

Update tags or categories page titles

1. Find "tags_page_title" or "categories_page_title"
2. Replace the value
3. Save

---

Why This File Exists

The blog has its own configuration file for one reason: context. The blog is a different section of the site with its own visual style (icons in navbar) and its own set of auxiliary pages (tags, categories). Keeping its configuration separate from the homepage config means:

1. You can change the blog navbar without affecting the docs navbar
2. You can write blog-specific SEO descriptions
3. You can use icons in the blog navbar but not in the docs navbar

This is the same “separation of concerns” pattern used throughout Astro Docus.

---

Rules to Remember

1. Keep valid JSON. No trailing commas, no comments, double quotes only.
2. Do not rename keys unless you also update the widgets that read them.
3. The navbar array must have nav, icon, and link. The blog navbar widget expects all three.
4. Use /src/assets/... paths for icons and images.
5. Internal links start with /. External links start with https://.
6. Save the file and reload the browser to see changes during development.

---

Quick Recap

blogpage.json
├── url, title, description, icon, image     → metadata
├── categories_page_title, categories_page_description  → /categories/
├── tags_page_title, tags_page_description   → /tags/
└── navbar[]                                 → blog navigation menu
     └── { nav, icon, link }

• One file controls the blog index and navbar.
• Metadata drives SEO and social previews.
• Navbar items have icons — unique to the blog context.
• Tags and categories have their own titles — edit them independently.
• Changes appear immediately in dev mode.

👉 Next: docs/blog/post-detail.md — how individual blog posts render.

# Blog — Introduction

```markdown
---
title: Blog Introduction
description: Overview of the custom blog system in Astro Docus — a full multi-purpose documentation and blog platform.
tableOfContents: true
---

## 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

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

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

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`, and `categories`
- **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

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

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

The blog system has several sub-topics. They will be documented one by one:

1. **Blog Index Page** — configuring `/blog/` via `blogpage.json`
2. **Blog Structure** — where posts live and how folders are organized
3. **Blog Frontmatter** — title, date, tags, categories, description
4. **Blog Listing** — how the `/blog/` page is built
5. **Blog Post Detail** — how individual posts render
6. **Tags** — tag archives and tag navigation
7. **Categories** — category archives
8. **RSS Feed** — how the feed is generated
9. **Pagination** — how pages are split

Each topic gets its own page under `docs/blog/`.

---

## 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 needed

The 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.