How-to

Step-by-step guides for common Zorto tasks.

Tutorials #

Build a blog: end-to-end from zorto init to deployment
Build a docs site: sections, sidebar navigation, content_dirs

Content #

Add a blog: posts, tags, pagination, drafts, and feeds
Use executable code blocks: Python and Bash at build time
Organize content with sections: nested sections, templates, external content
Set up multiple authors: taxonomies and frontmatter

Presentations #

Create a presentation: slide deck from one markdown file per slide

Visualizations #

Create charts with matplotlib: static line charts, bar charts, subplots
Create interactive charts with plotly: hover, zoom, and pan
Create charts with altair: declarative statistical visualizations
Create charts with seaborn: distribution plots, box plots, heatmaps

Customization #

Customize your theme: override templates, styles, and shortcodes
Customize navigation and footer: menus, logo, social links, copyright
Add a favicon: site icon setup
Add a 404 page: custom error page

Search #

Add search: enable DuckDB-backed client-side search

Deployment #

Deploy your site: Netlify, GitHub Pages, Vercel, Cloudflare
Set up a custom domain: DNS, HTTPS, subdomains
Add a sitemap: sitemap.xml and robots.txt
Optimize for SEO: meta tags, Open Graph, llms.txt

Help #

Troubleshooting: common errors and how to fix them

Add a 404 page

The built-in themes ship with a 404.html template that renders automatically. If you want a custom one, create your own templates/404.html in your project root.

Add a blog

Set up a blog with posts, tags, pagination, and an Atom feed.

Add a favicon

Place your favicon file in the static/ directory at your project root. Zorto copies everything in static/ to public/ at build time, so static/favicon.svg becomes /favicon.svg.

Add a sitemap

Zorto generates sitemap.xml automatically. It is enabled by default — no configuration needed.

Add search

Zorto search is a DuckDB data app. Generate a public .ddb file with a search_pages table, ship it as a static asset, and point the theme at it.

Advanced templating

Go beyond basic templates with macros, block inheritance, loops, pagination, and dynamic data from config.extra.

Build a blog

Create a blog from scratch with posts, tags, pagination, custom themes, and deployment.

Build a docs site

Create a documentation site with organized sections, sidebar navigation, and optional external content sources using content_dirs.

Create a presentation

This guide walks through creating a slide deck with Zorto. The example uses a reveal.js template, but the content model also works with native HTML/CSS/JS deck templates.

Create charts with altair

Use Altair in executable code blocks to create declarative statistical visualizations that render as interactive HTML.

Create charts with matplotlib

Use matplotlib in executable code blocks to generate static charts that render as inline PNGs.

Create charts with seaborn

Use seaborn in executable code blocks to create statistical visualizations. Seaborn builds on matplotlib, so charts render as inline PNGs.

Create interactive charts with plotly

Use plotly in executable code blocks to generate interactive charts with hover, zoom, and pan.

Customize navigation and footer

The built-in themes render navigation and footer from config.toml values. No template overrides needed for common cases.

Customize styles with SCSS and CSS

Override colors, fonts, spacing, and layout without forking a theme.

Customize your theme

Override templates, styles, and shortcodes without forking the theme.

Deploy your site

Zorto builds static files — HTML, CSS, JS — that can be hosted on any static hosting provider. No server-side runtime required.

Manage assets

Serve images, fonts, and other static files alongside your Zorto site.

Optimize builds

Speed up builds for large sites and control what Zorto generates.

Optimize for SEO and discoverability

Configure your Zorto site for search engine visibility and AI agent discovery.

Organize content with sections

Structure your site for different content types, audiences, or topics using Zorto's section system.

Set up a custom domain

Connect your own domain to a Zorto site hosted on any static hosting provider.

Set up multiple authors

Use taxonomies and page frontmatter to attribute content to different authors.

Troubleshooting

Common issues and how to fix them.

Use executable code blocks

Run Python and Bash at build time to generate dynamic content in your static site.