Guides explain the workflows used to build and maintain a Sarde site. Use them when the task spans several reference entries or when the order of steps matters.
Start with content
Read these first when setting up a new site or moving existing Markdown into Sarde:
- Project Structure explains where content, templates, assets, and configuration live.
- Content and Collections explains how folders become docs, blogs, courses, and other collections.
- Writing Content covers frontmatter, page bundles, drafts, scheduled content, and expiring pages.
- Internal Links covers link syntax, resolution rules, anchor validation, and URL composition across languages and versions.
- Navigation and Sidebar covers sidebar ordering, grouping, icons, badges, and manual overrides.
- Tabbed Navigation explains tab-based navigation for multi-area docs collections.
- Blog and Taxonomies covers blog collections, tags, categories, and taxonomy pages.
Polish the site
Use these guides after the core content exists:
- Search explains the offline search index and search UI.
- SEO and Feeds covers metadata, feeds, sitemap, robots.txt, and social cards.
- Link Validation and Linting covers link checks, content linting, and report formats.
- Icons explains inline SVG icons from Iconify sets and local files.
- Page Banners covers per-page and cascading banner notices via frontmatter.
Customize the output
Use these when changing the appearance or output behavior:
- Themes and Styling covers presets, tokens, dark mode, and CSS layer order.
- Branding covers the site logo, light and dark variants, and the favicon.
- Layouts and Templates explains layout selection, template lookup, components, and partials.
- Images and Assets covers responsive images, static files, bundled CSS, and bundled JavaScript.
- Homepage covers the eight homepage templates and hero configuration.
- Code Blocks covers syntax highlighting, line highlighting, diffs, titles, and code groups.
- Internationalization covers multi-language sites, localized URLs, and RTL support.
- Versioning covers multi-version documentation with version switcher and search scoping.
- Slides and Presentations links to the Teaching section for slide decks, presentation layout, and course integration.
Project Structure
Understand what each directory and config file in a Sarde project does
Content and Collections
Learn how folders of Markdown become auto-detected blogs, docs, courses, and other collections
Writing Content
Cover frontmatter fields, page bundles, drafts, scheduled content, and expiring pages
Internal Links
Link between pages using relative paths or collection-root paths. Sarde resolves them to final URLs with the correct base path, language, and version.
Navigation and Sidebar
Control sidebar ordering, grouping, icons, and collapsed state through frontmatter and directory structure
Tabbed Navigation
Split a large docs collection into top-level tabs with an auto-detected or configured tab switcher
Homepage
Choose and configure one of eight built-in homepage templates for content/_index.md
Blog and Taxonomies
Set up date-sorted blog collections with feeds, list layouts, tags, and categories
Images and Assets
Place and link images, PDFs, and other assets from Markdown. Configure responsive image generation, LQIP placeholders, and CSS/JS bundling.
Code Blocks
Set up syntax highlighting, titles, line markers, copy controls, and grouped tabs for code blocks
Search
Understand the offline, client-side Orama search index and how to configure it
SEO and Feeds
Configure meta tags, structured data, sitemaps, RSS/Atom feeds, and social cards
Themes and Styling
Choose a theme preset, override design tokens, and control dark mode and CSS layer order
Branding
Add a site logo to the header and set a favicon. Covers light and dark variants, sizing, image formats, and favicon auto-detection.
Slides and Presentations
Write once, publish as both a website and a slide presentation.
Icons
Insert inline SVG icons from Iconify sets or local files using the :icon[name] extension
Internationalization
Configure multi-language sites with localized URLs, fallback pages, and a language switcher
Versioning
Set up multiple documentation versions with a version switcher, URL prefixes, and search scoping
Link Validation and Linting
Configure internal link checking, external URL probing, and content linting policies
Page Banners
Display contextual banners at the top of individual pages using frontmatter.