Metadata-Version: 2.4
Name: aai-octavo
Version: 0.0.4
Summary: Build static sites from markdown and notebooks.
Author-email: Rens <rd@answer.ai>
License: Apache-2.0
Project-URL: Repository, https://github.com/AnswerDotAI/octavo
Project-URL: Documentation, https://AnswerDotAI.github.io/octavo/
Keywords: nbdev
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aidialog>=0.0.30
Requires-Dist: aihist>=0.1.2
Requires-Dist: fastcore>=2.2.34
Requires-Dist: mdhtml[fill,hl]>=0.1.44
Requires-Dist: pagefind[bin]
Requires-Dist: watchdog
Dynamic: license-file

# octavo

Build static sites from notebooks and markdown




<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

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:

```text
docs/
    octavo.yml
    index.md
    guide.ipynb
```

In `docs/octavo.yml`:

```yaml
title: My project
output: ../_site
```

The output path is relative to `docs/`. Sources and output must be separate directories; neither may contain the other. The build replaces the output directory, so reserve it for generated files.

In `docs/index.md`:

```markdown
---
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/`, build the site:

```bash
octavo-build docs
```

To serve it locally and rebuild after edits:

```bash
octavo-preview docs
```

Both commands default to the current directory when the path is omitted. Preview opens a browser; refresh it after a rebuild. Use `octavo-preview --help` for server options.

An explicit `--output preview` overrides the YAML destination and is relative to your working directory.

Python callers can use `Site.from_dir('docs').build()` from `octavo.site`.

Your site is saved in `_site/`:

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

## Migrating from Quarto

For `octavo-migrate-quarto`, read the [migration guide](https://AnswerDotAI.github.io/octavo/migrate.html).
