# Blog

Great Docs supports adding a blog to your documentation site using Quarto's native [listing](https://quarto.org/docs/websites/website-listings.html) feature. Blog posts are automatically sorted by date, display author and category metadata, and include built-in search.


# Quick Start

1.  Create a `blog/` directory with each post in its own subdirectory:

<!-- -->

    my-package/
    ├── blog/
    │   ├── welcome-post/
    │   │   └── index.qmd
    │   └── v0.2-release/
    │       └── index.qmd
    ├── great-docs.yml
    └── ...

2.  Add the blog section to `great-docs.yml` with `type: blog`:


    great-docs.yml


``` yaml
sections:
  - title: Blog
    dir: blog
    type: blog
```


3.  Run `great-docs build`: a **Blog** link appears in the navbar, and the listing page is generated automatically.


# Post Structure

Each blog post lives in its own subdirectory under `blog/`, with an `index.qmd` file containing the post content. This is the same convention used by Quarto's blog projects.

    blog/
    ├── welcome-post/
    │   ├── index.qmd
    │   └── images/
    │       └── hero.png       # Post-specific images
    ├── v0.2-release/
    │   └── index.qmd
    └── tips-and-tricks/
        └── index.qmd


## Post Frontmatter

Each post's `index.qmd` should include frontmatter with metadata that Quarto uses for the listing page:


    blog/welcome-post/index.qmd


``` yaml
---
title: "Welcome to Our Blog"
author: Vivian Smith
date: 2024-01-15
categories: [announcements, getting-started]
description: "An introduction to us and what we're building."
---
```


| Field | Required | Description |
|----|----|----|
| `title` | Yes | Post title, shown in listing and as the page heading |
| `date` | Yes | Publication date (`YYYY-MM-DD`); controls sort order |
| `author` | No | Author name, displayed in the listing |
| `categories` | No | List of tags for filtering posts |
| `description` | No | Summary text shown in the listing |
| `image` | No | Thumbnail image for the listing card |


# Listing Page

When no `index.qmd` exists at the root of the blog directory, Great Docs auto-generates one using Quarto's `listing:` directive:

``` yaml
---
title: "Blog"
listing:
  type: default
  sort: "date desc"
  contents:
    - "**.qmd"
---
```

This produces a listing page that:

- sorts posts by date (newest first)
- shows title, author, date, description, and categories
- includes client-side search across all posts
- links each entry to the full post


## Custom Listing Page

To customize the listing layout, provide your own `blog/index.qmd`. For example, to use a table layout:


    blog/index.qmd


``` yaml
---
title: "Blog"
listing:
  type: table
  sort: "date desc"
  feed: true
  contents:
    - "**.qmd"
---
```


Quarto supports three listing types:

| Type      | Description                         |
|-----------|-------------------------------------|
| `default` | Card-style listing with thumbnails  |
| `grid`    | Grid of equal-sized cards           |
| `table`   | Compact table with sortable columns |

See [Quarto Listings](https://quarto.org/docs/websites/website-listings.html) for all options, including custom templates and feeds.


# How It Differs from Default Sections

Blog sections (`type: blog`) differ from default sections in several ways:

| Feature | Default Sections | Blog Sections |
|----|----|----|
| Index page | Card grid (auto-generated) | Quarto listing (auto-generated) |
| Sidebar | Yes (with page links) | No |
| Sort order | Alphabetical | By date (newest first) |
| Post metadata | `title`, `description` | `title`, `date`, `author`, `categories`, `description` |
| Frontmatter modification | Adds `bread-crumbs: false` | No modification |
| File structure | Flat `.qmd` files | Subdirectories with `index.qmd` |


# Configuration

The blog section is configured as part of the `sections` array in `great-docs.yml`:


    great-docs.yml


``` yaml
sections:
  - title: Blog              # Navbar link text
    dir: blog                # Source directory
    type: blog               # Use Quarto's listing directive
    navbar_after: Reference  # Position in navbar (optional)
```


# Example: Full Blog Setup

Here's a complete example with three posts:


## Directory Structure

    my-package/
    ├── blog/
    │   ├── introducing-the-project/
    │   │   └── index.qmd
    │   ├── february-update/
    │   │   └── index.qmd
    │   └── v0.2-release/
    │       └── index.qmd
    ├── my_package/
    │   └── __init__.py
    ├── great-docs.yml
    └── pyproject.toml


## Configuration


    great-docs.yml


``` yaml
sections:
  - title: Blog
    dir: blog
    type: blog
```


## Blog Post


    blog/v0.2-release/index.qmd


``` markdown
---
title: "Version 0.2 Release Notes"
author: Vivian Smith
date: 2024-03-10
categories: [releases]
description: "New features and improvements in v0.2."
---

We're happy to announce the v0.2 release!

## New Features

- blog support via Quarto's listing directive
- improved dark mode styling
- better section card colors

## Breaking Changes

None in this release.
```


# Next Steps

A blog gives your project a voice beyond reference documentation. Use it for release announcements, tutorials, design rationale, or anything else that benefits from a chronological format. Great Docs handles the listing page, categories, and date sorting so you can focus on writing.

- [Custom Sections](custom-sections.md) covers adding non-blog sections (examples, tutorials, etc.)
- [Configuration](configuration.md) covers all available `great-docs.yml` options