octavo

Build static sites from notebooks and markdown

Octavo builds static sites from notebooks and Markdown. It writes an HTML page and a GitHub-flavored Markdown file for each document, with links resolved for each format. Sites include navigation, a table of contents, and Pagefind search.

It's like quarto but smaller, faster, and ours.

Get started

Install from pypi: pip install aai-octavo

To build a site create a directory containing Markdown files or notebooks and an octavo.yml file. For example:

docs/
    octavo.yml
    index.md
    guide.ipynb

In docs/octavo.yml:

title: My project
output: ../_site

The output path is relative to docs/. The build replaces that directory; use a destination reserved for generated files.

In docs/index.md:

---
title: My project
---

Read the [guide](guide.ipynb).

Write the guide in docs/guide.ipynb. Links use source filenames. Octavo rewrites this link to guide.html for HTML output and retains guide.md for Markdown output.

From the directory containing docs/, run the following Python code.

from octavo.site import Site
Site.from_dir('docs').build()

Your site is saved in _site/:

index.html  # html pages
guide.html
index.md    # md pages
guide.md
pagefind/   # helpers
_octavo/