Content and Collections

Collections turn folders of related Markdown files into organized areas of a
site, such as a blog, documentation library, course, or reference section.

What are collections

A collection is any top-level subdirectory inside content/ that contains
Markdown content.

content/
  blog/
    _index.md
    photosynthesis-lab.md
  docs/
    _index.md
    lesson-planning.md

blog/ and docs/ become separate collections. Sarde uses the folder name as
the collection name and URL mount, so these folders render at /blog/ and
/docs/.

This is a convention, not a special setup step. Any top-level folder with
Markdown content becomes a collection. Known folder names only change the
defaults Sarde applies.

What collections contain

Collections contain the pages, sections, and navigation data for one area of a
site.

Markdown files placed directly in content/ are standalone pages, not
collections. The homepage content/_index.md is also outside any collection.

Auto-detection rules

Sarde recognizes three collection families by directory name:

Naming a directory blog/ is a convention. Sarde auto-detects it as a date-sorted collection with feeds, but any directory name works. A directory named updates/ would get default-type behavior unless overridden in sarde.yaml.

Per-collection defaults

Each collection type comes with pre-configured behavior:

Blog collections

• Sorted by date descending (newest first)
• Paginated at 10 posts per page
• RSS/Atom feeds enabled
• Prev/next links wired from the sorted post order

Docs collections

• Sorted by order ascending (controlled by frontmatter sidebar.order or numeric filename prefix)
• Docs layout with sidebar navigation
• Collapsible sidebar with 4-level depth
• Table of contents enabled (H2 through H4)
• Prev/next links wired from the sidebar order

Slides collections

• Sorted by date descending (newest first)
• Gallery list page with card grid (thumbnails, slide counts, tags, authors)
• Deck pages auto-default to layout: presentation (full-viewport slide viewer, no configuration needed)
• Course subdirectories render as nested galleries
• See the Teaching section for the full guide

Default collections

• Sorted by title ascending
• Default layout (no sidebar, no TOC)

Overriding collection config

Override any auto-detected default in sarde.yaml under the collections key:

sarde.yaml

collections:
  blog:
    sort: "title asc"
    paginate: 20
    feed: false
  docs:
    sidebar:
      collapsed_by_default: true
      max_depth: 3
    toc:
      depth: 3
  tutorials:
    sort: "order asc"
    layout: "docs"

Available per-collection settings:

See Configuration for the complete reference.

Sections and _index.md

Subdirectories within a collection become sections. Each section can have an _index.md file that defines the section's title, order, and metadata.

content/docs/
  _index.md                 # Collection root
  getting-started.md
  guides/
    _index.md               # Section: "Guides"
    writing-content.md
    code-blocks.md
  reference/
    _index.md               # Section: "Reference"
    configuration.md
    frontmatter.md

The _index.md file is optional. Without it, Sarde infers the section title from the directory name and assigns a default order of 0.

Use frontmatter in _index.md to control the section's sidebar position and label:

---
title: Guides
sidebar:
  order: 2
  label: "How-To Guides"
---

Sections can nest deeper than the sidebar renders. Sarde builds a tree from the
directory structure, then sidebar rendering follows the collection's
sidebar.max_depth setting.

Transparent sections

A transparent section groups files on disk without appearing as a separate level in the sidebar. Its child pages are hoisted into the parent section.

Set transparent: true in the section's _index.md:

---
title: Internal
transparent: true
---

content/docs/
  _index.md
  internal/                 # transparent section
    _index.md               # transparent: true
    page-a.md
    page-b.md
  other-page.md

Result: The sidebar shows page-a and page-b alongside other-page, not nested under an "Internal" group. The internal/ directory still organizes the files on disk.

Transparent sections affect navigation structure only. A transparent section can
still render its own section page. Add render: false to the section's
_index.md when the section acts as a navigation group without its own
page.

Page bundles

A page bundle is an index.md file (not _index.md) placed in a directory alongside non-Markdown files. The sibling files (images, PDFs, data files) become assets of that page.

content/blog/
  my-post/
    index.md                # Page bundle
    cover.jpg               # Bundle asset
    diagram.svg             # Bundle asset

Reference bundle assets with relative paths in the Markdown:

![Cover image](cover.jpg)

Page bundles keep content and its assets together, making pages self-contained and portable.

Content at the root

Markdown files placed directly in content/ (not inside a collection directory) become standalone pages. The homepage _index.md at content/_index.md is a special case that renders using the configured homepage template.

Node kinds

Sarde classifies every Markdown file into one of five kinds:

See Frontmatter for all available frontmatter fields and auto-inference rules.