diff --git a/nbdev/__init__.py b/nbdev/__init__.py
index f244760cc..0af6c802d 100644
--- a/nbdev/__init__.py
+++ b/nbdev/__init__.py
@@ -4,6 +4,7 @@
 
 - `nbdev.extract_attachments`: A preprocessor that extracts all of the attachments from the notebook file. The extracted attachments are returned in the 'resources' dictionary.
 - `nbdev.moddocs`: # Module docs: creating them from existing notebooks
+- `nbdev.octavo`: Build nbdev documentation with Octavo
 - `nbdev.skill`: Write, read and review nbdev notebooks as source, documentation, examples and tests. You MUST read this before any work on a project with notebooks."""
 
 __version__ = "3.3.26"
diff --git a/nbdev/_modidx.py b/nbdev/_modidx.py
index 1456e861a..79dda9ad3 100644
--- a/nbdev/_modidx.py
+++ b/nbdev/_modidx.py
@@ -213,6 +213,28 @@
                                'nbdev.migrate.migrate_nb': ('api/migrate.html#migrate_nb', 'nbdev/migrate.py'),
                                'nbdev.migrate.nbdev_migrate': ('api/migrate.html#nbdev_migrate', 'nbdev/migrate.py'),
                                'nbdev.migrate.nbdev_migrate_config': ('api/migrate.html#nbdev_migrate_config', 'nbdev/migrate.py')},
+            'nbdev.octavo': { 'nbdev.octavo.OctavoProc': ('api/octavo.html#octavoproc', 'nbdev/octavo.py'),
+                              'nbdev.octavo.OctavoProc.__call__': ('api/octavo.html#octavoproc.__call__', 'nbdev/octavo.py'),
+                              'nbdev.octavo.OctavoProc.__init__': ('api/octavo.html#octavoproc.__init__', 'nbdev/octavo.py'),
+                              'nbdev.octavo.OctavoProc.add_links': ('api/octavo.html#octavoproc.add_links', 'nbdev/octavo.py'),
+                              'nbdev.octavo.OctavoProc.nb_proc': ('api/octavo.html#octavoproc.nb_proc', 'nbdev/octavo.py'),
+                              'nbdev.octavo.OctavoProc.procs': ('api/octavo.html#octavoproc.procs', 'nbdev/octavo.py'),
+                              'nbdev.octavo._create_octavo_cfg': ('api/octavo.html#_create_octavo_cfg', 'nbdev/octavo.py'),
+                              'nbdev.octavo._migrate_octavo': ('api/octavo.html#_migrate_octavo', 'nbdev/octavo.py'),
+                              'nbdev.octavo._octavo_output': ('api/octavo.html#_octavo_output', 'nbdev/octavo.py'),
+                              'nbdev.octavo._octavo_sidebar': ('api/octavo.html#_octavo_sidebar', 'nbdev/octavo.py'),
+                              'nbdev.octavo._quarto_config': ('api/octavo.html#_quarto_config', 'nbdev/octavo.py'),
+                              'nbdev.octavo._script_md': ('api/octavo.html#_script_md', 'nbdev/octavo.py'),
+                              'nbdev.octavo.local_libraries': ('api/octavo.html#local_libraries', 'nbdev/octavo.py'),
+                              'nbdev.octavo.nbdev_migrate_octavo': ('api/octavo.html#nbdev_migrate_octavo', 'nbdev/octavo.py'),
+                              'nbdev.octavo.octavo_config': ('api/octavo.html#octavo_config', 'nbdev/octavo.py'),
+                              'nbdev.octavo.octavo_docs': ('api/octavo.html#octavo_docs', 'nbdev/octavo.py'),
+                              'nbdev.octavo.octavo_preview': ('api/octavo.html#octavo_preview', 'nbdev/octavo.py'),
+                              'nbdev.octavo.octavo_readme': ('api/octavo.html#octavo_readme', 'nbdev/octavo.py'),
+                              'nbdev.octavo.render_script': ('api/octavo.html#render_script', 'nbdev/octavo.py'),
+                              'nbdev.octavo.repl_script_frontmatter_keys': ( 'api/octavo.html#repl_script_frontmatter_keys',
+                                                                             'nbdev/octavo.py'),
+                              'nbdev.octavo.script_pages': ('api/octavo.html#script_pages', 'nbdev/octavo.py')},
             'nbdev.process': { 'nbdev.process.NBProcessor': ('api/process.html#nbprocessor', 'nbdev/process.py'),
                                'nbdev.process.NBProcessor.__init__': ('api/process.html#nbprocessor.__init__', 'nbdev/process.py'),
                                'nbdev.process.NBProcessor._proc': ('api/process.html#nbprocessor._proc', 'nbdev/process.py'),
@@ -304,6 +326,7 @@
                               'nbdev.quarto._install_linux': ('api/quarto.html#_install_linux', 'nbdev/quarto.py'),
                               'nbdev.quarto._install_mac': ('api/quarto.html#_install_mac', 'nbdev/quarto.py'),
                               'nbdev.quarto._nbglob_docs': ('api/quarto.html#_nbglob_docs', 'nbdev/quarto.py'),
+                              'nbdev.quarto._octavo': ('api/quarto.html#_octavo', 'nbdev/quarto.py'),
                               'nbdev.quarto._pre': ('api/quarto.html#_pre', 'nbdev/quarto.py'),
                               'nbdev.quarto._pre_docs': ('api/quarto.html#_pre_docs', 'nbdev/quarto.py'),
                               'nbdev.quarto._readme_cands': ('api/quarto.html#_readme_cands', 'nbdev/quarto.py'),
diff --git a/nbdev/doclinks.py b/nbdev/doclinks.py
index 9f49f55fa..9d52e5fcd 100644
--- a/nbdev/doclinks.py
+++ b/nbdev/doclinks.py
@@ -213,27 +213,27 @@ def _get_exps(mod):
 def _lineno(sym, fname): return _get_exps(fname).get(sym, None) if fname else None
 
 # %% ../nbs/api/05_doclinks.ipynb #c1b8c9fa
-def _qual_sym(s, settings):
+def _qual_sym(s, settings, local=False):
     "Get qualified nb, py, and github paths for a symbol s"
     if not isinstance(s,tuple): return s
     nb,py = s
     nbbase = urljoin(settings["doc_host"]+'/',settings["doc_baseurl"])
-    nb = urljoin(nbbase+'/', nb)
+    nb = '/' + nb.lstrip('/') if local else urljoin(nbbase+'/', nb)
     gh = urljoin(settings["git_url"]+'/', f'blob/{settings["branch"]}/{py}')
     return nb,py,gh
 
-def _qual_mod(mod_d, settings): return {sym:_qual_sym(s, settings) for sym,s in mod_d.items()}
-def _qual_syms(entries):
+def _qual_mod(mod_d, settings, local=False): return {sym:_qual_sym(s, settings, local) for sym,s in mod_d.items()}
+def _qual_syms(entries, local=False):
     settings = entries['settings']
     if 'doc_host' not in settings: return entries
-    return {'syms': {mod:_qual_mod(d, settings) for mod,d in entries['syms'].items()}, 'settings':settings}
+    return {'syms': {mod:_qual_mod(d, settings, local) for mod,d in entries['syms'].items()}, 'settings':settings}
 
 # %% ../nbs/api/05_doclinks.ipynb #53505fa4
 _re_backticks = re.compile(r'`([^`\s]+?)(?:\(\))?`')
 
 # %% ../nbs/api/05_doclinks.ipynb #3a24b883
 @lru_cache(None)
-def _build_lookup_table(strip_libs=None, incl_libs=None, skip_mods=None):
+def _build_lookup_table(strip_libs=None, incl_libs=None, skip_mods=None, local_lib=None):
     cfg = get_config(also_settings=True)
     if strip_libs is None:
         try: strip_libs = cfg.get('strip_libs') or cfg.lib_name
@@ -248,7 +248,7 @@ def _build_lookup_table(strip_libs=None, incl_libs=None, skip_mods=None):
     
     for o in eps:
         if incl_libs is not None and o.dist.name not in incl_libs: continue
-        try: entries[o.name] = _qual_syms(o.load())
+        try: entries[o.name] = _qual_syms(o.load(), local=o.name in tuplify(local_lib))
         except Exception: pass
     py_syms = merge(*L(o['syms'].values() for o in entries.values()).concat())
     for m in strip_libs:
@@ -266,8 +266,8 @@ def _build_lookup_table(strip_libs=None, incl_libs=None, skip_mods=None):
 # %% ../nbs/api/05_doclinks.ipynb #3257b6bf
 class NbdevLookup:
     "Mapping from symbol names to docs and source URLs"
-    def __init__(self, strip_libs=None, incl_libs=None, skip_mods=None, ns=None):
-        self.entries,self.syms = _build_lookup_table(strip_libs, incl_libs, skip_mods)
+    def __init__(self, strip_libs=None, incl_libs=None, skip_mods=None, ns=None, local_lib=None):
+        self.entries,self.syms = _build_lookup_table(strip_libs, incl_libs, skip_mods, local_lib)
         self.aliases = {n:o.__name__ for n,o in (ns or {}).items() if isinstance(o, ModuleType)}
         
     def __getitem__(self, s): 
diff --git a/nbdev/octavo.py b/nbdev/octavo.py
new file mode 100644
index 000000000..86e0b5da0
--- /dev/null
+++ b/nbdev/octavo.py
@@ -0,0 +1,288 @@
+r"""Build nbdev documentation with Octavo
+
+Octavo is an alternative to Quarto for building a documentation website from nbdev notebooks. Install `nbdev[octavo]` to use it. A project selects Octavo by placing `octavo.yml` in its configured notebooks directory. Projects without that file continue to use Quarto and do not import Octavo.
+
+The usual `nbdev-docs` command builds the site. Octavo currently builds all pages together. File-selection options are rejected unless left at their defaults; `n_workers` affects only Quarto builds.
+
+Run `nbdev-export` before building to update the generated Python modules and symbol indexes. `nbdev-readme` and `nbdev-contributing` also use Octavo for these projects. `nbdev-prepare` still exports, tests, and cleans notebooks, but skips Quarto configuration generation.
+
+For an existing Quarto project, `nbdev-migrate-octavo` converts documentation sources in place. The converted sources are not intended to work unchanged with both builders. Use `nbdev-preview` to serve the site and rebuild after edits. Refresh the browser manually.
+
+## Migration instructions (share this with your AI)
+
+Octavo builds into the same output directory as Quarto and replaces what's there. The migration also converts the sources in place, and they won't build with Quarto afterwards, even if you keep `_quarto.yml`. So save the Quarto site first:
+
+1. Commit or back up the project.
+2. From the project root, run `nbdev-docs` while the project still uses Quarto. Check that the build works, and note any failures it already has, so you don't mistake them for migration problems later.
+3. Copy the whole built site, including assets and search files, to a directory outside the project's source and output directories. This copy is the baseline you compare against.
+4. Run `nbdev-migrate-octavo` from the project root. Read its changes and everything it prints: it reports the settings it couldn't carry over.
+5. Run `nbdev-docs` again to build with Octavo. If the build fails, keep its output for diagnosis.
+
+`nbdev-migrate-octavo` renames `.qmd` sources to `.md`, updates references to them, converts directives, and moves a page's `subtitle` to `description`. Octavo reads Quarto's other front matter and settings names as they are. The migration writes `octavo.yml` from `_quarto.yml` and `nbdev.yml`, and leaves an existing `octavo.yml` alone. It doesn't port the site's design. It leaves stylesheet files unchanged, and it doesn't add the stylesheets listed under `format.html.css` in `_quarto.yml` to `octavo.yml`. Stylesheets that a page lists in its own front matter still load.
+
+Read the original `_quarto.yml`, `nbdev.yml` and `pyproject.toml`, and the new `octavo.yml`. Go through the checks below that apply to the project, skipping features it doesn't use, and propose a short migration plan. Ask me before accepting anything that loses behavior.
+
+- **Styles and custom pages.** Octavo's HTML has no Bootstrap or Quarto classes. Look at the rendered Octavo HTML before reusing old CSS, and copy over only the rules that still apply. Don't enable an old stylesheet wholesale or add a compatibility layer. Check narrow screens too.
+- **Wide content.** Octavo has no equivalent of Quarto's `page-layout: full` or column classes such as `.column-page` and `.column-screen-inset-right`. Widen those pages with your own CSS, in a stylesheet listed in the page's `css` front matter.
+- **Layouts and tables of contents.** Octavo reads Quarto's `page-layout`, `toc` and `toc-depth` with the same meanings, but of the `page-layout` values it supports only `custom`, for a hand-built page. Check pages that used `article` or `full`, and compare tables of contents with the baseline on ordinary pages as well as custom ones.
+- **Sidebar.** If the project has a hand-written `sidebar.yml` (`custom_sidebar` in `pyproject.toml`), the migration turns it into `sidebar-links` in `octavo.yml`. Compare its sections and order with the baseline. Add the pages behind any entries it reported as dropped, such as `auto` or globs, as explicit links.
+- **Scripts.** The migration doesn't carry over scripts that Quarto added through `include-in-header`, `include-after-body` or raw HTML. Load them with Octavo's `js` setting, in `octavo.yml` for the whole site or in a page's front matter. Octavo loads them as module scripts (`<script type="module">`).
+- **Maths.** The migration sets `math: dollars`, Quarto's `$...$` syntax. Check the pages with maths. A literal dollar sign in a paragraph that also has maths needs escaping as `\$`.
+- **Conditional and embedded content.** Compare `when-format` and `unless-format` blocks with the originals, in both the HTML and the Markdown output. The conversion doesn't always keep exclusion conditions, and Markdown inside an HTML-only block isn't rendered. Where needed, turn HTML-only content into a raw `{=html}` block. Check each result rather than rewriting every block by pattern.
+- **`{python}` blocks.** Octavo runs the `{python}` blocks in `.md` files on every build, and the page shows only their output, not the code. Quarto also showed the code. Compare pages that have these blocks with the baseline. If the project set `execute: enabled: false` in `_quarto.yml`, the blocks didn't run under Quarto at all.
+- **Shortcodes.** Octavo doesn't support Quarto shortcodes such as `{{< include file.md >}}` or `{{< video url >}}`. They appear as literal text. Search the sources for `{{<` and report each use.
+- **Render scripts and processors.** If the project has render scripts (such as `page.md.py` or `drawing.svg.py`) or custom nbdev processors, check the content and assets they produce.
+- **Code that finds docs by name.** Search the whole project for `.qmd`, including build scripts, tests, generators and contributor docs, and update paths, globs and extension checks. A glob that matches nothing fails silently. Run the full test suite, not only `nbdev-docs`, and check that tests that read doc pages still find them. Regenerate saved notebook outputs that contain `.qmd` links.
+- **Published files.** Quarto published only linked files and declared resources. Octavo publishes every visible file in the notebooks directory (no part of its path starts with `.` or `_`), as a page or as a copied file. Compare the output file list with the baseline. To keep stray files such as READMEs or notes out, add glob patterns to `exclude` in `octavo.yml`. Patterns are relative to the notebooks directory, and a pattern that matches a directory excludes everything in it. Don't exclude Quarto-only files: they're deleted at the end.
+- **Navigation and URLs.** Check navbar links, dropdowns, icons, favicon, footer and existing public URLs. Restore icons the migration dropped, and keep the existing footer. Markdown copies of notebook pages move from `page.html.md` to `page.md`, and Octavo doesn't redirect the old addresses. Report this rather than working around it.
+- **Settings that weren't carried over.** List the site and page settings the migration reported as having no Octavo equivalent, and any theme options and preview preferences. Octavo uses a page's `image` front matter as its link preview image when `site-url` is set, and a page can set its own `open-graph` or `twitter-card` options. It doesn't pick a preview image from the page content, so list the pages that relied on that. For each setting, propose a replacement or say it's dropped. Quarto's repo-actions links, such as "Report an issue", are dropped on purpose: don't list them.
+- **Build hooks.** If the project has custom build hooks, keep the outputs they produce with nbdev's `docs_post_build` setting, and check the links in any indexes they generate.
+- **Output directory.** A relative `output` in `octavo.yml` is relative to the notebooks directory. Without it, nbdev uses `doc_path`, which is relative to the project. Check that this is the directory the deployment workflow publishes.
+
+Once I've approved the plan, make the changes in small steps, running `nbdev-export` before each build. Then:
+
+- run `nbdev-docs` and the project's other Markdown commands, such as `nbdev-readme`;
+- compare the HTML, Markdown, assets and other build outputs with the baseline, and check a few API signatures, symbol links and GitHub source links;
+- sort the differences into failures the baseline already had, expected changes, and regressions.
+
+A clean build doesn't show that the site works in a browser. Serve the baseline and the new site separately, and check that each server points at the directory you meant. Serve the new site under its real subpath, such as `/project/`, not only at `/`. Then, on a few representative pages at desktop and phone widths, test:
+
+- navigation in the menu's
+- anchors and images;
+- search, following results from the homepage and from a nested page;
+- the optional features you found in the checks above.
+
+Report what you changed, which checks you actually ran, the differences you couldn't resolve, the settings that weren't carried over, and the decisions I need to make. Keep the original configuration and the baseline until I've reviewed the migration.
+
+After the review, delete `_quarto.yml`, plus the files it lists under `metadata-files` and `syntax-definitions` that nothing else in the project uses, such as `nbdev.yml` and `sidebar.yml`.
+
+Docs: https://nbdev.fast.ai/api/octavo.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/20_octavo.ipynb.
+
+# %% auto #0
+__all__ = ['NBDEV_KEYS', 'OctavoProc', 'local_libraries', 'render_script', 'script_pages', 'octavo_config', 'octavo_docs',
+           'octavo_preview', 'octavo_readme', 'repl_script_frontmatter_keys', 'nbdev_migrate_octavo']
+
+# %% ../nbs/api/20_octavo.ipynb #7b098bb5
+from contextlib import redirect_stdout
+from io import StringIO
+from fastcore.utils import *
+from fastcore.script import call_parse
+import yaml, shutil, subprocess, threading, webbrowser
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from octavo import *
+from octavo.migrate import *
+from mdhtml import md2gfm
+from .config import get_config, import_obj, _load_toml
+from .doclinks import NbdevLookup
+from .process import NBProcessor
+from .processors import FilterDefaults, add_links
+from .serve import _is_qpy
+from .quarto import _doc_mtime_not_older, fs_watchdog
+
+# %% ../nbs/api/20_octavo.ipynb #1cc66460
+class OctavoProc(FilterDefaults):
+    "Prepare notebook content, metadata, and symbol links for Octavo"
+    def __init__(self, local_lib=None, strip_libs=None): self.nl = NbdevLookup(strip_libs=strip_libs or local_lib, local_lib=local_lib)
+    def add_links(self, cell): return add_links(cell, nl=self.nl)
+    def procs(self): return L(self.add_links if o is add_links else o for o in super().procs())
+    def nb_proc(self, nb): return NBProcessor(nb=nb, procs=self.procs(), rm_directives=False)
+
+    def __call__(self, nb):
+        super().__call__(nb)
+        if getattr(nb, 'frontmatter_', None) and nb.cells[0].cell_type=='raw': nb.cells[0].cell_type = 'markdown'
+
+# %% ../nbs/api/20_octavo.ipynb #9a0258ee
+def local_libraries(cfg):
+    "Names of the project's declared nbdev symbol indexes"
+    proj = _load_toml(cfg.config_file).get('project', {})
+    return tuple(proj.get('entry-points', {}).get('nbdev', {}))
+
+# %% ../nbs/api/20_octavo.ipynb #f9f85ebf
+def render_script(path):
+    "Execute a double-suffix render script and return its printed output with optional page metadata"
+    path = Path(path)
+    if path.suffix!='.py' or len(path.suffixes)<2: return
+    fm = _is_qpy(path) if path.name.endswith('.md.py') else None
+    f = StringIO()
+    with redirect_stdout(f): exec(compile(path.read_text(encoding='utf-8'), str(path), 'exec'), {})
+    return (f'---\n{fm}\n---\n\n' if fm else '') + f.getvalue()
+
+# %% ../nbs/api/20_octavo.ipynb #e85c51f3
+def script_pages(root,         # Documentation directory
+                 exclude=None): # Glob patterns of paths to skip, as in Octavo's `exclude` setting
+    "Render scripts under `root`: `*.md.py` as `Page`s, anything else as `GeneratedFile`s"
+    root,pages,files = Path(root),L(),L()
+    for rel in source_files(root, exclude).map(Path).filter(lambda o: o.suffix=='.py'):
+        if (txt:=render_script(root/rel)) is None: continue
+        dest = rel.with_suffix('')
+        if dest.suffix=='.md': pages.append(Page(str(rel), txt, nm=page_nm(dest)))
+        else: files.append(GeneratedFile(str(rel), str(dest), txt))
+    return pages,files
+
+# %% ../nbs/api/20_octavo.ipynb #d6904375
+def octavo_config(root):
+    "Settings from `octavo.yml`, as Octavo's `read_cfg` reads them; the file must exist"
+    if not (p := Path(root)/CFG_FILE).is_file(): raise FileNotFoundError(p)
+    return read_cfg(root)
+
+# %% ../nbs/api/20_octavo.ipynb #f6830357
+def octavo_docs(
+    path:str=None, # Path to the project or its notebooks
+):
+    "Create Octavo docs and run the optional docs_post_build callback"
+    cfg = get_config(path)
+    settings = {'output': cfg.doc_path, **octavo_config(cfg.nbs_path)}
+    with working_directory(cfg.config_path):
+        pages,files = script_pages(cfg.nbs_path, settings.get('exclude'))
+        docs = scan(cfg.nbs_path, nbproc=OctavoProc(local_lib=local_libraries(cfg)), exclude=settings.get('exclude')) + pages
+        site = Site(docs, root=cfg.nbs_path, files=files, **settings)
+        if (miss := site.build()): print(miss)
+        if (post := cfg.get('docs_post_build')):
+            out = Path(site.settings['output']).expanduser()
+            if not out.is_absolute(): out = cfg.nbs_path/out
+            import_obj(post)(out.resolve(), cfg)
+
+# %% ../nbs/api/20_octavo.ipynb #db88c5c9
+def octavo_preview(
+    path:str=None, # Path to the project or its notebooks
+    port:int=None, # HTTP port (defaults to 8000)
+    host:str=None, # Bind address (defaults to localhost)
+    no_browser:bool=False, # Do not open a browser
+):
+    "Serve documentation and rebuild when project files change"
+    cfg = get_config(path)
+    root = cfg.config_path.resolve()
+    settings = octavo_config(cfg.nbs_path)
+    out = (cfg.nbs_path/Path(settings.get('output', cfg.doc_path)).expanduser()).resolve()
+    if root.is_relative_to(out) or cfg.nbs_path.resolve().is_relative_to(out): raise ValueError('Output must not contain sources')
+    changed = threading.Event()
+
+    def rebuild():
+        try: subprocess.run(['nbdev-docs', '--path', str(root)], cwd=root, check=True)
+        except subprocess.CalledProcessError:
+            shutil.rmtree(out, ignore_errors=True)
+            out.mkdir(parents=True, exist_ok=True)
+            (out/'index.html').write_text('<h1>Build failed - see terminal</h1>')
+            print('Build failed; waiting for another edit.', flush=True)
+
+    def on_change(event):
+        if event.event_type not in ('created', 'modified', 'deleted', 'moved'): return
+        if event.is_directory and event.event_type=='modified': return
+        for name in (event.src_path, getattr(event, 'dest_path', '')):
+            if not name: continue
+            src = Path(name).resolve()
+            if src.is_relative_to(out) or not src.is_relative_to(root): continue
+            if any(p.startswith('.') or p=='__pycache__' for p in src.relative_to(root).parts): continue
+            changed.set()
+
+    handler = partial(SimpleHTTPRequestHandler, directory=str(out))
+    with ThreadingHTTPServer((host or 'localhost', 8000 if port is None else port), handler) as server:
+        url = f'http://{host or "localhost"}:{server.server_port}'
+        with fs_watchdog(on_change, root):
+            rebuild()
+            threading.Thread(target=server.serve_forever, daemon=True).start()
+            try:
+                print(f'{url} - refresh your browser after rebuilding', flush=True)
+                if not no_browser: webbrowser.open(url)
+                while True:
+                    changed.wait()
+                    changed.clear()
+                    while changed.wait(0.2): changed.clear()
+                    rebuild()
+            finally: server.shutdown()
+
+# %% ../nbs/api/20_octavo.ipynb #0d38402b
+def octavo_readme(
+    path:str=None, # Path to the project or its notebooks
+    chk_time:bool=False, # Only build if the source is newer
+    contributing:bool=False, # Render CONTRIBUTING instead of README
+):
+    "Render a repository Markdown document from a notebook's stored outputs"
+    cfg = get_config(path)
+    nbname = cfg.get('contributing_nb', 'contributing.ipynb') if contributing else cfg.readme_nb
+    root = Path(path).absolute() if path else cfg.nbs_path
+    src = root/nbname
+    if not src.exists(): src = cfg.nbs_path/nbname
+    if not src.exists(): return
+    name = 'CONTRIBUTING' if contributing else 'README'
+    dest = cfg.config_path/f'{name}.md'
+    if chk_time and _doc_mtime_not_older(dest, src): return
+    octavo_config(cfg.nbs_path)
+    with working_directory(cfg.config_path):
+        proc = OctavoProc(strip_libs=local_libraries(cfg))
+        doc = md2doc(ipynb2md(src, nbproc=proc))
+        head = f'# {doc.meta["title"]}\n\n' if doc.meta.get('title') else ''
+        if desc:=doc.meta.get('description'): head += f'{desc}\n\n'
+        md2gfm(head + doc.body, dest=dest, imgdir=cfg.config_path/f'{src.stem}_files', raw=('md', 'html'))
+
+# %% ../nbs/api/20_octavo.ipynb #deb7ee06
+def _quarto_config(nbs_path): return read_quarto_config(nbs_path/'_quarto.yml'),read_quarto_config(nbs_path/'nbdev.yml')
+
+# %% ../nbs/api/20_octavo.ipynb #127739bd
+def _octavo_output(nbs_path, qy, ny):
+    "Return a Quarto output override relative to notebooks, or None when doc_path suffices"
+    out_dir = (ny.get('project', {}) or {}).get('output-dir') or (qy.get('project', {}) or {}).get('output-dir')
+    if not out_dir: return
+    cfg = get_config(nbs_path)
+    out_dir = (cfg.config_path/Path(out_dir).expanduser()).resolve()
+    if out_dir == cfg.doc_path.resolve(): return
+    return os.path.relpath(out_dir, Path(nbs_path).resolve()).replace(os.sep, '/')
+
+# %% ../nbs/api/20_octavo.ipynb #e0912069
+def _octavo_sidebar(nbs_path):
+    "Convert the project's custom sidebar when enabled"
+    p = Path(nbs_path)/'sidebar.yml'
+    if not get_config(nbs_path).custom_sidebar or not p.exists(): return {}
+    sb = nested_idx(yaml.safe_load(p.read_text()) or {}, 'website', 'sidebar') or {}
+    return quarto_sidebar(sb, p)
+
+# %% ../nbs/api/20_octavo.ipynb #2f2d4b3b
+def _create_octavo_cfg(nbs_path):
+    "Convert Quarto settings with nbdev's overlay, output path and custom sidebar"
+    nbs_path = Path(nbs_path).resolve()
+    qy,ny = _quarto_config(nbs_path)
+    output = _octavo_output(nbs_path, qy, ny)
+    cfg = quarto_config(qy, nbs_path, overrides=ny) | _octavo_sidebar(nbs_path)
+    if output is not None: cfg['output'] = output
+    return cfg
+
+# %% ../nbs/api/20_octavo.ipynb #5927e211
+_script_fm = re.compile(r'\A(?P<q>"{3}|\'{3})---\n(?P<fm>.*?)\n---(?P=q)', re.DOTALL)
+
+def _script_md(m):
+    "Frontmatter block from a `_script_fm` match on a render script"
+    return f"---\n{m.group('fm')}\n---\n"
+
+def repl_script_frontmatter_keys(s):
+    "Normalize a render script's leading YAML docstring for Octavo"
+    if not (m := _script_fm.match(s)): return s
+    old = _script_md(m)
+    new = repl_frontmatter_keys(old)
+    if new == old: return s
+    return m.group('q') + new.rstrip('\n') + m.group('q') + s[m.end():]
+
+# %% ../nbs/api/20_octavo.ipynb #c4b4478c
+NBDEV_KEYS = {'skip_exec', 'skip_showdoc'}
+
+def _migrate_octavo(path):
+    "Migrate documents and nbdev render scripts using the project's configuration"
+    path = Path(path).expanduser()
+    scripts = source_files(path).map(lambda o: path/o).filter(lambda p: p.name.endswith('.qmd.py'))
+    script_moves = {p:p.with_name(p.name.removesuffix('.qmd.py')+'.md.py') for p in scripts}
+    moves = migrate_quarto(path, config=_create_octavo_cfg, extra_keys=NBDEV_KEYS, extra_moves=script_moves)
+    for p in script_moves.values():
+        migrate_md_file(p, [repl_script_frontmatter_keys])
+        if m := _script_fm.match(p.read_text()):
+            report_page_keys(p, extra_keys=NBDEV_KEYS, metadata=frontmatter(_script_md(m))[0])
+    return moves
+
+# %% ../nbs/api/20_octavo.ipynb #e332ece4
+@call_parse
+def nbdev_migrate_octavo(
+    path:str=None, # Documentation directory (defaults to configured nbs_path)
+):
+    "Migrate Quarto-era nbdev project to Octavo"
+    moves = _migrate_octavo(get_config().nbs_path if path is None else path)
+    for old,new in moves.items(): print(f'{old} -> {new}')
diff --git a/nbdev/processors.py b/nbdev/processors.py
index 222e8564f..6354e0024 100644
--- a/nbdev/processors.py
+++ b/nbdev/processors.py
@@ -121,9 +121,9 @@ def _default_exp(nb):
     return default_exp.group(1) if default_exp else None
 
 # %% ../nbs/api/10_processors.ipynb #03e8fece-bf92-4a1d-9f8b-ef209107ff95
-def add_links(cell):
+def add_links(cell, nl=None):
     "Add links to markdown cells"
-    nl = NbdevLookup()
+    if nl is None: nl = NbdevLookup()
     if cell.cell_type == 'markdown': cell.source = nl.linkify(cell.source)
     for o in cell.get('outputs', []):
         if hasattr(o, 'data') and hasattr(o['data'], 'text/markdown'):
diff --git a/nbdev/quarto.py b/nbdev/quarto.py
index b436cd3ba..9efa23cc6 100644
--- a/nbdev/quarto.py
+++ b/nbdev/quarto.py
@@ -13,6 +13,7 @@
 import subprocess,sys,shutil,ast,warnings,traceback
 from os import system
 from contextlib import contextmanager
+from inspect import signature
 
 from .config import *
 from .doclinks import *
@@ -75,7 +76,7 @@ def _sort(a):
 
 _def_file_re = r'\.(?:ipynb|qmd|html)$'
 
-@delegates
+@delegates(nbglob_cli)
 def _nbglob_docs(
     path:str=None, # Path to notebooks
     file_glob:str=None, # Only include files matching glob    
@@ -272,12 +273,19 @@ def _save_cached_readme(cache, cfg):
     if _rdmi.exists(): _copytree(_rdmi, cfg.config_path/_rdmi.name)
 
 
+# %% ../nbs/api/14_quarto.ipynb #803e45af
+def _octavo(path=None):
+    if not (get_config(path).nbs_path/'octavo.yml').is_file(): return None
+    from nbdev import octavo
+    return octavo
+
 # %% ../nbs/api/14_quarto.ipynb #45d6bb5d
 @call_parse
 def nbdev_readme(
     path:str=None, # Path to notebooks (or project root)
     chk_time:bool=False): # Only build if out of date
     "Create README.md from readme_nb (index.ipynb by default). Skips if the file doesn't exist."
+    if backend:=_octavo(path): return backend.octavo_readme(path, chk_time=chk_time)
     cfg = get_config(path)
     path = Path(path).absolute() if path else cfg.nbs_path
     if not (path/cfg.readme_nb).exists(): path = cfg.nbs_path  # given a project root, fall back to its configured nbs
@@ -315,6 +323,7 @@ def nbdev_contributing(
     chk_time:bool=False  # Only build if out-of-date
 ):
     """Create CONTRIBUTING.md from contributing_nb (defaults to 'contributing.ipynb' if present). Skips if the file doesn't exist."""
+    if backend:=_octavo(path): return backend.octavo_readme(path, chk_time=chk_time, contributing=True)
     cfg = get_config()
     path = Path(path) if path else cfg.nbs_path
     contrib_nb_name = cfg.get('contributing_nb', 'contributing.ipynb')
@@ -341,7 +350,12 @@ def nbdev_docs(
     path:str=None, # Path to notebooks
     n_workers:int=defaults.cpus,  # Preprocessing and Quarto workers (0 or 1: serial)
     **kwargs):
-    "Create Quarto docs"
+    "Build docs with the backend selected by the project's configuration"
+    if (backend:=_octavo(path)):
+        params = signature(_nbglob_docs).parameters
+        unsupported = [k for k,v in kwargs.items() if k not in params or v != params[k].default]
+        if unsupported: raise ValueError(f'Octavo does not support these Quarto file filters: {", ".join(unsupported)}')
+        return backend.octavo_docs(path)
     cache,cfg,_ = _pre_docs(path, n_workers=n_workers, **kwargs)
     render_quarto(cache, cache/cfg.doc_path.name, n_workers=n_workers)
     shutil.rmtree(cfg.doc_path, ignore_errors=True)
@@ -356,7 +370,7 @@ def prepare():
     nbdev_export.__wrapped__()
     nbdev.test.nbdev_test.__wrapped__()
     nbdev.clean.nbdev_clean.__wrapped__()
-    refresh_quarto_yml()
+    if not _octavo(): refresh_quarto_yml()
     nbdev_readme.__wrapped__(chk_time=True)
     nbdev_contributing.__wrapped__(chk_time=True)
 
@@ -388,6 +402,11 @@ def nbdev_preview(
     n_workers:int=defaults.cpus,  # Preprocessing and Quarto workers (0 or 1: serial)
     **kwargs):
     "Preview docs locally"
+    if backend:=_octavo(path):
+        params = signature(_nbglob_docs).parameters
+        unsupported = [k for k,v in kwargs.items() if k not in params or v != params[k].default]
+        if unsupported: raise ValueError(f'Octavo does not support these Quarto flags: {", ".join(unsupported)}')
+        return backend.octavo_preview(path, port=port, host=host, no_browser=no_browser)
     os.environ['QUARTO_PREVIEW']='1'
     cache,cfg,path = _pre_docs(path, n_workers=n_workers, **kwargs)
     site = cache/cfg.doc_path.name
diff --git a/nbs/api/05_doclinks.ipynb b/nbs/api/05_doclinks.ipynb
index fa950e2e2..82fb9088c 100644
--- a/nbs/api/05_doclinks.ipynb
+++ b/nbs/api/05_doclinks.ipynb
@@ -602,20 +602,20 @@
    "outputs": [],
    "source": [
     "#| export\n",
-    "def _qual_sym(s, settings):\n",
+    "def _qual_sym(s, settings, local=False):\n",
     "    \"Get qualified nb, py, and github paths for a symbol s\"\n",
     "    if not isinstance(s,tuple): return s\n",
     "    nb,py = s\n",
     "    nbbase = urljoin(settings[\"doc_host\"]+'/',settings[\"doc_baseurl\"])\n",
-    "    nb = urljoin(nbbase+'/', nb)\n",
+    "    nb = '/' + nb.lstrip('/') if local else urljoin(nbbase+'/', nb)\n",
     "    gh = urljoin(settings[\"git_url\"]+'/', f'blob/{settings[\"branch\"]}/{py}')\n",
     "    return nb,py,gh\n",
     "\n",
-    "def _qual_mod(mod_d, settings): return {sym:_qual_sym(s, settings) for sym,s in mod_d.items()}\n",
-    "def _qual_syms(entries):\n",
+    "def _qual_mod(mod_d, settings, local=False): return {sym:_qual_sym(s, settings, local) for sym,s in mod_d.items()}\n",
+    "def _qual_syms(entries, local=False):\n",
     "    settings = entries['settings']\n",
     "    if 'doc_host' not in settings: return entries\n",
-    "    return {'syms': {mod:_qual_mod(d, settings) for mod,d in entries['syms'].items()}, 'settings':settings}"
+    "    return {'syms': {mod:_qual_mod(d, settings, local) for mod,d in entries['syms'].items()}, 'settings':settings}"
    ]
   },
   {
@@ -660,7 +660,7 @@
    "source": [
     "#| export\n",
     "@lru_cache(None)\n",
-    "def _build_lookup_table(strip_libs=None, incl_libs=None, skip_mods=None):\n",
+    "def _build_lookup_table(strip_libs=None, incl_libs=None, skip_mods=None, local_lib=None):\n",
     "    cfg = get_config(also_settings=True)\n",
     "    if strip_libs is None:\n",
     "        try: strip_libs = cfg.get('strip_libs') or cfg.lib_name\n",
@@ -675,7 +675,7 @@
     "    \n",
     "    for o in eps:\n",
     "        if incl_libs is not None and o.dist.name not in incl_libs: continue\n",
-    "        try: entries[o.name] = _qual_syms(o.load())\n",
+    "        try: entries[o.name] = _qual_syms(o.load(), local=o.name in tuplify(local_lib))\n",
     "        except Exception: pass\n",
     "    py_syms = merge(*L(o['syms'].values() for o in entries.values()).concat())\n",
     "    for m in strip_libs:\n",
@@ -724,8 +724,8 @@
     "#| export\n",
     "class NbdevLookup:\n",
     "    \"Mapping from symbol names to docs and source URLs\"\n",
-    "    def __init__(self, strip_libs=None, incl_libs=None, skip_mods=None, ns=None):\n",
-    "        self.entries,self.syms = _build_lookup_table(strip_libs, incl_libs, skip_mods)\n",
+    "    def __init__(self, strip_libs=None, incl_libs=None, skip_mods=None, ns=None, local_lib=None):\n",
+    "        self.entries,self.syms = _build_lookup_table(strip_libs, incl_libs, skip_mods, local_lib)\n",
     "        self.aliases = {n:o.__name__ for n,o in (ns or {}).items() if isinstance(o, ModuleType)}\n",
     "        \n",
     "    def __getitem__(self, s): \n",
diff --git a/nbs/api/10_processors.ipynb b/nbs/api/10_processors.ipynb
index d79d3dd38..4aefe0fd6 100644
--- a/nbs/api/10_processors.ipynb
+++ b/nbs/api/10_processors.ipynb
@@ -347,9 +347,9 @@
    "outputs": [],
    "source": [
     "#| export\n",
-    "def add_links(cell):\n",
+    "def add_links(cell, nl=None):\n",
     "    \"Add links to markdown cells\"\n",
-    "    nl = NbdevLookup()\n",
+    "    if nl is None: nl = NbdevLookup()\n",
     "    if cell.cell_type == 'markdown': cell.source = nl.linkify(cell.source)\n",
     "    for o in cell.get('outputs', []):\n",
     "        if hasattr(o, 'data') and hasattr(o['data'], 'text/markdown'):\n",
diff --git a/nbs/api/14_quarto.ipynb b/nbs/api/14_quarto.ipynb
index b485f3f36..2fa66e38a 100644
--- a/nbs/api/14_quarto.ipynb
+++ b/nbs/api/14_quarto.ipynb
@@ -40,6 +40,7 @@
     "import subprocess,sys,shutil,ast,warnings,traceback\n",
     "from os import system\n",
     "from contextlib import contextmanager\n",
+    "from inspect import signature\n",
     "\n",
     "from nbdev.config import *\n",
     "from nbdev.doclinks import *\n",
@@ -162,7 +163,7 @@
     "\n",
     "_def_file_re = r'\\.(?:ipynb|qmd|html)$'\n",
     "\n",
-    "@delegates\n",
+    "@delegates(nbglob_cli)\n",
     "def _nbglob_docs(\n",
     "    path:str=None, # Path to notebooks\n",
     "    file_glob:str=None, # Only include files matching glob    \n",
@@ -521,6 +522,20 @@
     "    if _rdmi.exists(): _copytree(_rdmi, cfg.config_path/_rdmi.name)\n"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "803e45af",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "def _octavo(path=None):\n",
+    "    if not (get_config(path).nbs_path/'octavo.yml').is_file(): return None\n",
+    "    from nbdev import octavo\n",
+    "    return octavo"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -534,6 +549,7 @@
     "    path:str=None, # Path to notebooks (or project root)\n",
     "    chk_time:bool=False): # Only build if out of date\n",
     "    \"Create README.md from readme_nb (index.ipynb by default). Skips if the file doesn't exist.\"\n",
+    "    if backend:=_octavo(path): return backend.octavo_readme(path, chk_time=chk_time)\n",
     "    cfg = get_config(path)\n",
     "    path = Path(path).absolute() if path else cfg.nbs_path\n",
     "    if not (path/cfg.readme_nb).exists(): path = cfg.nbs_path  # given a project root, fall back to its configured nbs\n",
@@ -558,7 +574,7 @@
    "id": "a6f1a4ce",
    "metadata": {},
    "source": [
-    "`nbdev-readme` calls \"quarto render,\" which is explained in the Quarto guide [here](https://quarto.org/docs/projects/code-execution.html).\n",
+    "`nbdev-readme` selects Octavo when the configured notebooks directory contains `octavo.yml`; otherwise it calls `quarto render`. `nbdev-contributing` uses the same backend selection. Octavo uses stored outputs, extracts embedded images, and leaves authored relative destinations unchanged. See `octavo_readme`.\n",
     "\n",
     "Pandoc's gfm writer hard-wraps prose at 72 columns by default; `-M wrap:preserve` keeps each paragraph's line breaks exactly as authored in the notebook instead.\n",
     "\n",
@@ -612,6 +628,7 @@
     "    chk_time:bool=False  # Only build if out-of-date\n",
     "):\n",
     "    \"\"\"Create CONTRIBUTING.md from contributing_nb (defaults to 'contributing.ipynb' if present). Skips if the file doesn't exist.\"\"\"\n",
+    "    if backend:=_octavo(path): return backend.octavo_readme(path, chk_time=chk_time, contributing=True)\n",
     "    cfg = get_config()\n",
     "    path = Path(path) if path else cfg.nbs_path\n",
     "    contrib_nb_name = cfg.get('contributing_nb', 'contributing.ipynb')\n",
@@ -679,7 +696,12 @@
     "    path:str=None, # Path to notebooks\n",
     "    n_workers:int=defaults.cpus,  # Preprocessing and Quarto workers (0 or 1: serial)\n",
     "    **kwargs):\n",
-    "    \"Create Quarto docs\"\n",
+    "    \"Build docs with the backend selected by the project's configuration\"\n",
+    "    if (backend:=_octavo(path)):\n",
+    "        params = signature(_nbglob_docs).parameters\n",
+    "        unsupported = [k for k,v in kwargs.items() if k not in params or v != params[k].default]\n",
+    "        if unsupported: raise ValueError(f'Octavo does not support these Quarto file filters: {\", \".join(unsupported)}')\n",
+    "        return backend.octavo_docs(path)\n",
     "    cache,cfg,_ = _pre_docs(path, n_workers=n_workers, **kwargs)\n",
     "    render_quarto(cache, cache/cfg.doc_path.name, n_workers=n_workers)\n",
     "    shutil.rmtree(cfg.doc_path, ignore_errors=True)\n",
@@ -725,7 +747,7 @@
     "    nbdev_export.__wrapped__()\n",
     "    nbdev.test.nbdev_test.__wrapped__()\n",
     "    nbdev.clean.nbdev_clean.__wrapped__()\n",
-    "    refresh_quarto_yml()\n",
+    "    if not _octavo(): refresh_quarto_yml()\n",
     "    nbdev_readme.__wrapped__(chk_time=True)\n",
     "    nbdev_contributing.__wrapped__(chk_time=True)"
    ]
@@ -737,7 +759,7 @@
    "source": [
     "## Preview\n",
     "\n",
-    "`nbdev-preview` keeps its own copy of the site in the `_proc` cache, rendering new or changed pages on startup and as you edit; it doesn't change `doc_path`. When the cache has no site it starts from a copy of the one in `doc_path`, so unchanged pages from the last `nbdev-docs` run aren't rendered again. If any processed page has missing or older HTML output, it rebuilds the site in parallel using the same `--n-workers` setting as `nbdev-docs`, then starts Quarto's usual preview and input watching. Use `nbdev-preview --render` to rebuild everything, including changes to shared configuration or filters."
+    "For Quarto projects, `nbdev-preview` keeps its own copy of the site in the `_proc` cache, rendering new or changed pages on startup and as you edit; it doesn't change `doc_path`. When the cache has no site it starts from a copy of the one in `doc_path`, so unchanged pages from the last `nbdev-docs` run aren't rendered again. If any processed page has missing or older HTML output, it rebuilds the site in parallel using the same `--n-workers` setting as `nbdev-docs`, then starts Quarto's usual preview and input watching. Use `nbdev-preview --render` to rebuild everything, including changes to shared configuration or filters."
    ]
   },
   {
@@ -783,6 +805,11 @@
     "    n_workers:int=defaults.cpus,  # Preprocessing and Quarto workers (0 or 1: serial)\n",
     "    **kwargs):\n",
     "    \"Preview docs locally\"\n",
+    "    if backend:=_octavo(path):\n",
+    "        params = signature(_nbglob_docs).parameters\n",
+    "        unsupported = [k for k,v in kwargs.items() if k not in params or v != params[k].default]\n",
+    "        if unsupported: raise ValueError(f'Octavo does not support these Quarto flags: {\", \".join(unsupported)}')\n",
+    "        return backend.octavo_preview(path, port=port, host=host, no_browser=no_browser)\n",
     "    os.environ['QUARTO_PREVIEW']='1'\n",
     "    cache,cfg,path = _pre_docs(path, n_workers=n_workers, **kwargs)\n",
     "    site = cache/cfg.doc_path.name\n",
@@ -834,7 +861,11 @@
    ]
   }
  ],
- "metadata": {},
+ "metadata": {
+  "solveit": {
+   "use_thinking": false
+  }
+ },
  "nbformat": 4,
  "nbformat_minor": 5
 }
diff --git a/nbs/api/20_octavo.ipynb b/nbs/api/20_octavo.ipynb
new file mode 100644
index 000000000..2697628e3
--- /dev/null
+++ b/nbs/api/20_octavo.ipynb
@@ -0,0 +1,1600 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "c0313881",
+   "metadata": {},
+   "source": [
+    "# Octavo\n",
+    "\n",
+    "> Build nbdev documentation with Octavo\n",
+    "- order: 21"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1a6d574e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| default_exp octavo"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "56ff9208",
+   "metadata": {},
+   "source": [
+    "#| export \n",
+    "Octavo is an alternative to Quarto for building a documentation website from nbdev notebooks. Install `nbdev[octavo]` to use it. A project selects Octavo by placing `octavo.yml` in its configured notebooks directory. Projects without that file continue to use Quarto and do not import Octavo.\n",
+    "\n",
+    "The usual `nbdev-docs` command builds the site. Octavo currently builds all pages together. File-selection options are rejected unless left at their defaults; `n_workers` affects only Quarto builds.\n",
+    "\n",
+    "Run `nbdev-export` before building to update the generated Python modules and symbol indexes. `nbdev-readme` and `nbdev-contributing` also use Octavo for these projects. `nbdev-prepare` still exports, tests, and cleans notebooks, but skips Quarto configuration generation.\n",
+    "\n",
+    "For an existing Quarto project, `nbdev-migrate-octavo` converts documentation sources in place. The converted sources are not intended to work unchanged with both builders. Use `nbdev-preview` to serve the site and rebuild after edits. Refresh the browser manually.\n",
+    "\n",
+    "## Migration instructions (share this with your AI)\n",
+    "\n",
+    "Octavo builds into the same output directory as Quarto and replaces what's there. The migration also converts the sources in place, and they won't build with Quarto afterwards, even if you keep `_quarto.yml`. So save the Quarto site first:\n",
+    "\n",
+    "1. Commit or back up the project.\n",
+    "2. From the project root, run `nbdev-docs` while the project still uses Quarto. Check that the build works, and note any failures it already has, so you don't mistake them for migration problems later.\n",
+    "3. Copy the whole built site, including assets and search files, to a directory outside the project's source and output directories. This copy is the baseline you compare against.\n",
+    "4. Run `nbdev-migrate-octavo` from the project root. Read its changes and everything it prints: it reports the settings it couldn't carry over.\n",
+    "5. Run `nbdev-docs` again to build with Octavo. If the build fails, keep its output for diagnosis.\n",
+    "\n",
+    "`nbdev-migrate-octavo` renames `.qmd` sources to `.md`, updates references to them, converts directives, and moves a page's `subtitle` to `description`. Octavo reads Quarto's other front matter and settings names as they are. The migration writes `octavo.yml` from `_quarto.yml` and `nbdev.yml`, and leaves an existing `octavo.yml` alone. It doesn't port the site's design. It leaves stylesheet files unchanged, and it doesn't add the stylesheets listed under `format.html.css` in `_quarto.yml` to `octavo.yml`. Stylesheets that a page lists in its own front matter still load.\n",
+    "\n",
+    "Read the original `_quarto.yml`, `nbdev.yml` and `pyproject.toml`, and the new `octavo.yml`. Go through the checks below that apply to the project, skipping features it doesn't use, and propose a short migration plan. Ask me before accepting anything that loses behavior.\n",
+    "\n",
+    "- **Styles and custom pages.** Octavo's HTML has no Bootstrap or Quarto classes. Look at the rendered Octavo HTML before reusing old CSS, and copy over only the rules that still apply. Don't enable an old stylesheet wholesale or add a compatibility layer. Check narrow screens too.\n",
+    "- **Wide content.** Octavo has no equivalent of Quarto's `page-layout: full` or column classes such as `.column-page` and `.column-screen-inset-right`. Widen those pages with your own CSS, in a stylesheet listed in the page's `css` front matter.\n",
+    "- **Layouts and tables of contents.** Octavo reads Quarto's `page-layout`, `toc` and `toc-depth` with the same meanings, but of the `page-layout` values it supports only `custom`, for a hand-built page. Check pages that used `article` or `full`, and compare tables of contents with the baseline on ordinary pages as well as custom ones.\n",
+    "- **Sidebar.** If the project has a hand-written `sidebar.yml` (`custom_sidebar` in `pyproject.toml`), the migration turns it into `sidebar-links` in `octavo.yml`. Compare its sections and order with the baseline. Add the pages behind any entries it reported as dropped, such as `auto` or globs, as explicit links.\n",
+    "- **Scripts.** The migration doesn't carry over scripts that Quarto added through `include-in-header`, `include-after-body` or raw HTML. Load them with Octavo's `js` setting, in `octavo.yml` for the whole site or in a page's front matter. Octavo loads them as module scripts (`<script type=\"module\">`).\n",
+    "- **Maths.** The migration sets `math: dollars`, Quarto's `$...$` syntax. Check the pages with maths. A literal dollar sign in a paragraph that also has maths needs escaping as `\\$`.\n",
+    "- **Conditional and embedded content.** Compare `when-format` and `unless-format` blocks with the originals, in both the HTML and the Markdown output. The conversion doesn't always keep exclusion conditions, and Markdown inside an HTML-only block isn't rendered. Where needed, turn HTML-only content into a raw `{=html}` block. Check each result rather than rewriting every block by pattern.\n",
+    "- **`{python}` blocks.** Octavo runs the `{python}` blocks in `.md` files on every build, and the page shows only their output, not the code. Quarto also showed the code. Compare pages that have these blocks with the baseline. If the project set `execute: enabled: false` in `_quarto.yml`, the blocks didn't run under Quarto at all.\n",
+    "- **Shortcodes.** Octavo doesn't support Quarto shortcodes such as `{{< include file.md >}}` or `{{< video url >}}`. They appear as literal text. Search the sources for `{{<` and report each use.\n",
+    "- **Render scripts and processors.** If the project has render scripts (such as `page.md.py` or `drawing.svg.py`) or custom nbdev processors, check the content and assets they produce.\n",
+    "- **Code that finds docs by name.** Search the whole project for `.qmd`, including build scripts, tests, generators and contributor docs, and update paths, globs and extension checks. A glob that matches nothing fails silently. Run the full test suite, not only `nbdev-docs`, and check that tests that read doc pages still find them. Regenerate saved notebook outputs that contain `.qmd` links.\n",
+    "- **Published files.** Quarto published only linked files and declared resources. Octavo publishes every visible file in the notebooks directory (no part of its path starts with `.` or `_`), as a page or as a copied file. Compare the output file list with the baseline. To keep stray files such as READMEs or notes out, add glob patterns to `exclude` in `octavo.yml`. Patterns are relative to the notebooks directory, and a pattern that matches a directory excludes everything in it. Don't exclude Quarto-only files: they're deleted at the end.\n",
+    "- **Navigation and URLs.** Check navbar links, dropdowns, icons, favicon, footer and existing public URLs. Restore icons the migration dropped, and keep the existing footer. Markdown copies of notebook pages move from `page.html.md` to `page.md`, and Octavo doesn't redirect the old addresses. Report this rather than working around it.\n",
+    "- **Settings that weren't carried over.** List the site and page settings the migration reported as having no Octavo equivalent, and any theme options and preview preferences. Octavo uses a page's `image` front matter as its link preview image when `site-url` is set, and a page can set its own `open-graph` or `twitter-card` options. It doesn't pick a preview image from the page content, so list the pages that relied on that. For each setting, propose a replacement or say it's dropped. Quarto's repo-actions links, such as \"Report an issue\", are dropped on purpose: don't list them.\n",
+    "- **Build hooks.** If the project has custom build hooks, keep the outputs they produce with nbdev's `docs_post_build` setting, and check the links in any indexes they generate.\n",
+    "- **Output directory.** A relative `output` in `octavo.yml` is relative to the notebooks directory. Without it, nbdev uses `doc_path`, which is relative to the project. Check that this is the directory the deployment workflow publishes.\n",
+    "\n",
+    "Once I've approved the plan, make the changes in small steps, running `nbdev-export` before each build. Then:\n",
+    "\n",
+    "- run `nbdev-docs` and the project's other Markdown commands, such as `nbdev-readme`;\n",
+    "- compare the HTML, Markdown, assets and other build outputs with the baseline, and check a few API signatures, symbol links and GitHub source links;\n",
+    "- sort the differences into failures the baseline already had, expected changes, and regressions.\n",
+    "\n",
+    "A clean build doesn't show that the site works in a browser. Serve the baseline and the new site separately, and check that each server points at the directory you meant. Serve the new site under its real subpath, such as `/project/`, not only at `/`. Then, on a few representative pages at desktop and phone widths, test:\n",
+    "\n",
+    "- navigation in the menu's\n",
+    "- anchors and images;\n",
+    "- search, following results from the homepage and from a nested page;\n",
+    "- the optional features you found in the checks above.\n",
+    "\n",
+    "Report what you changed, which checks you actually ran, the differences you couldn't resolve, the settings that weren't carried over, and the decisions I need to make. Keep the original configuration and the baseline until I've reviewed the migration.\n",
+    "\n",
+    "After the review, delete `_quarto.yml`, plus the files it lists under `metadata-files` and `syntax-definitions` that nothing else in the project uses, such as `nbdev.yml` and `sidebar.yml`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7b098bb5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "from contextlib import redirect_stdout\n",
+    "from io import StringIO\n",
+    "from fastcore.utils import *\n",
+    "from fastcore.script import call_parse\n",
+    "import yaml, shutil, subprocess, threading, webbrowser\n",
+    "from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer\n",
+    "from octavo import *\n",
+    "from octavo.migrate import *\n",
+    "from mdhtml import md2gfm\n",
+    "from nbdev.config import get_config, import_obj, _load_toml\n",
+    "from nbdev.doclinks import NbdevLookup\n",
+    "from nbdev.process import NBProcessor\n",
+    "from nbdev.processors import FilterDefaults, add_links\n",
+    "from nbdev.serve import _is_qpy\n",
+    "from nbdev.quarto import _doc_mtime_not_older, fs_watchdog"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f93ea36d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| hide\n",
+    "import tempfile\n",
+    "from copy import deepcopy\n",
+    "from fastcore.test import *\n",
+    "from fastcore.nbio import new_nb, mk_cell, read_nb, write_nb\n",
+    "from nbdev.quarto import nbdev_docs"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "66b2ef09",
+   "metadata": {},
+   "source": [
+    "## Notebook processing\n",
+    "\n",
+    "Notebooks still need nbdev’s documentation processing before Octavo renders them. `OctavoProc` reuses that processing, including the project’s `doc_procs` and `skip_procs` settings.\n",
+    "\n",
+    "It keeps directives such as `#| echo: false` for Octavo to interpret. It also places generated page metadata, such as the title, in a Markdown cell that Octavo can read. The caller chooses whether generated symbol links point into the current site or to published documentation. Links written explicitly by the author are unchanged."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1cc66460",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "class OctavoProc(FilterDefaults):\n",
+    "    \"Prepare notebook content, metadata, and symbol links for Octavo\"\n",
+    "    def __init__(self, local_lib=None, strip_libs=None): self.nl = NbdevLookup(strip_libs=strip_libs or local_lib, local_lib=local_lib)\n",
+    "    def add_links(self, cell): return add_links(cell, nl=self.nl)\n",
+    "    def procs(self): return L(self.add_links if o is add_links else o for o in super().procs())\n",
+    "    def nb_proc(self, nb): return NBProcessor(nb=nb, procs=self.procs(), rm_directives=False)\n",
+    "\n",
+    "    def __call__(self, nb):\n",
+    "        super().__call__(nb)\n",
+    "        if getattr(nb, 'frontmatter_', None) and nb.cells[0].cell_type=='raw': nb.cells[0].cell_type = 'markdown'"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "78e180af",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'---\\ndescription: A notebook with rendering directives\\noutput-file: example.html\\ntitle: Example\\n\\n---\\n\\n'"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "source = new_nb([mk_cell('# Example\\n\\n> A notebook with rendering directives', 'markdown'),\n",
+    "                 mk_cell('Use `ModuleMaker`. See [production docs](https://nbdev.fast.ai/api/maker.html#modulemaker).', 'markdown'),\n",
+    "                 mk_cell('#| echo: false\\n1 + 1')])\n",
+    "source.path_ = Path('example.ipynb')\n",
+    "nb = deepcopy(source)\n",
+    "OctavoProc(local_lib='nbdev')(nb)\n",
+    "test_eq(nb.cells[0].cell_type, 'markdown')\n",
+    "text = '\\n'.join(c.source for c in nb.cells)\n",
+    "assert '[`ModuleMaker`](/api/maker.html#modulemaker)' in text\n",
+    "assert '[production docs](https://nbdev.fast.ai/api/maker.html#modulemaker)' in text\n",
+    "assert '#| echo: false' in text\n",
+    "quarto_nb = deepcopy(source)\n",
+    "FilterDefaults()(quarto_nb)\n",
+    "test_eq(quarto_nb.cells[0].cell_type, 'raw')\n",
+    "assert '#| echo: false' in '\\n'.join(c.source for c in quarto_nb.cells)\n",
+    "nb.cells[0].source"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ce1056e3",
+   "metadata": {},
+   "source": [
+    "A website build needs to distinguish this project’s API from dependencies’ APIs. References to this project should lead to pages in the site being built; references to dependencies should lead to their published documentation.\n",
+    "\n",
+    "nbdev identifies the project’s symbol indexes through `[project.entry-points.nbdev]` in `pyproject.toml`. It cannot infer those names from the package’s installation name. In the example below, the distribution is named `different-distribution`, but its symbol index is registered as `nbdev`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9a0258ee",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "def local_libraries(cfg):\n",
+    "    \"Names of the project's declared nbdev symbol indexes\"\n",
+    "    proj = _load_toml(cfg.config_file).get('project', {})\n",
+    "    return tuple(proj.get('entry-points', {}).get('nbdev', {}))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "86824851",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "/Users/rensdimmendaal/aai/ws/execnb/execnb/shell.py:172: UserWarning: Failed loading extension dialoghelper.bootstrap: Local skills already enabled for /Users/rensdimmendaal/aai/ws/nbdev/nbs/api\n",
+      "  for w in warns: warnings.warn(w)\n"
+     ]
+    }
+   ],
+   "source": [
+    "with tempfile.TemporaryDirectory() as d:\n",
+    "    project = Path(d)\n",
+    "    (project/'pyproject.toml').write_text('[project]\\nname = \"different-distribution\"\\n[project.entry-points.nbdev]\\nnbdev = \"nbdev._modidx:d\"\\n[tool.nbdev]\\n')\n",
+    "    libs = local_libraries(get_config(project))\n",
+    "    test_eq(libs, ('nbdev',))\n",
+    "    lookup = NbdevLookup(local_lib=libs)\n",
+    "    assert lookup.doc('nbdev.maker.ModuleMaker').startswith('/api/maker.html#')\n",
+    "    assert NbdevLookup().doc('nbdev.maker.ModuleMaker').startswith('https://')\n",
+    "    nb = deepcopy(source)\n",
+    "    with working_directory(project): OctavoProc(local_lib=libs)(nb)\n",
+    "    assert '[`ModuleMaker`](/api/maker.html#modulemaker)' in '\\n'.join(c.source for c in nb.cells)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5ad885db",
+   "metadata": {},
+   "source": [
+    "## Render scripts\n",
+    "\n",
+    "Render scripts generate documentation content during a build. Their filenames specify what they produce: `page.md.py` prints Markdown for a page, while `drawing.svg.py` prints an SVG image.\n",
+    "\n",
+    "nbdev executes each script and captures its printed output. Generated Markdown goes through Octavo’s page renderer. Other output is written verbatim under the filename without `.py`; for example, `drawing.svg.py` produces `drawing.svg`.\n",
+    "\n",
+    "A `.md.py` script can put YAML page metadata in its opening docstring. nbdev prepends that metadata to the printed Markdown.\n",
+    "\n",
+    "Render-script source files are not published. Ordinary single-suffix `.py` files are copied as assets rather than executed. An exception in a render script stops the build.\n",
+    "\n",
+    "Scripts under paths matched by the `exclude` setting in `octavo.yml` are not run."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f9f85ebf",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "def render_script(path):\n",
+    "    \"Execute a double-suffix render script and return its printed output with optional page metadata\"\n",
+    "    path = Path(path)\n",
+    "    if path.suffix!='.py' or len(path.suffixes)<2: return\n",
+    "    fm = _is_qpy(path) if path.name.endswith('.md.py') else None\n",
+    "    f = StringIO()\n",
+    "    with redirect_stdout(f): exec(compile(path.read_text(encoding='utf-8'), str(path), 'exec'), {})\n",
+    "    return (f'---\\n{fm}\\n---\\n\\n' if fm else '') + f.getvalue()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e85c51f3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "def script_pages(root,         # Documentation directory\n",
+    "                 exclude=None): # Glob patterns of paths to skip, as in Octavo's `exclude` setting\n",
+    "    \"Render scripts under `root`: `*.md.py` as `Page`s, anything else as `GeneratedFile`s\"\n",
+    "    root,pages,files = Path(root),L(),L()\n",
+    "    for rel in source_files(root, exclude).map(Path).filter(lambda o: o.suffix=='.py'):\n",
+    "        if (txt:=render_script(root/rel)) is None: continue\n",
+    "        dest = rel.with_suffix('')\n",
+    "        if dest.suffix=='.md': pages.append(Page(str(rel), txt, nm=page_nm(dest)))\n",
+    "        else: files.append(GeneratedFile(str(rel), str(dest), txt))\n",
+    "    return pages,files"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1864ec1d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "with tempfile.TemporaryDirectory() as d:\n",
+    "    d = Path(d)\n",
+    "    (d/'01_intro.md.py').write_text('\"\"\"---\\ntitle: Hi\\n---\"\"\"\\nprint(\"# Generated\")\\nprint(\"body\")')\n",
+    "    (d/'images').mkdir(); (d/'images/dot.svg.py').write_text('print(\"<svg/>\")')\n",
+    "    (d/'plain.md.py').write_text('print(\"# No frontmatter\")')\n",
+    "    (d/'ordinary.py').write_text('x = 1')\n",
+    "    (d/'_skip').mkdir(); (d/'_skip/no.md.py').write_text('\"\"\"---\\n---\"\"\"\\nprint(\"no\")')\n",
+    "    pages,files = script_pages(d)\n",
+    "    test_eq([p.dest for p in pages], ['intro.html','plain.html'])\n",
+    "    test_eq(pages[0].text, '---\\ntitle: Hi\\n---\\n\\n# Generated\\nbody\\n')\n",
+    "    test_eq(pages[0].meta['title'], 'Hi')\n",
+    "    test_eq(pages[1].text, '# No frontmatter\\n')\n",
+    "    test_eq([(f.src,f.dest,f.content) for f in files], [('images/dot.svg.py','images/dot.svg','<svg/>\\n')])\n",
+    "    test_eq(script_pages(d, exclude=['images'])[1], [])\n",
+    "    test_is(render_script(d/'ordinary.py'), None)\n",
+    "    (d/'bad.md.py').write_text('1/0')\n",
+    "    with expect_fail(ZeroDivisionError, contains='division'): script_pages(d)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a38f3e46",
+   "metadata": {},
+   "source": [
+    "## Post-build callback"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "24badb1f",
+   "metadata": {},
+   "source": [
+    "Some projects publish extra files alongside their documentation, such as an API list or an LLM context file. Use a post-build callback to generate these after the website has been built.\n",
+    "\n",
+    "Set `docs_post_build` to an importable `module:function` in `pyproject.toml`:\n",
+    "\n",
+    "```toml\n",
+    "[tool.nbdev]\n",
+    "docs_post_build = \"my_project.docbuild:build_extras\"\n",
+    "```\n",
+    "\n",
+    "After a successful site build, nbdev calls the function once with `(out, cfg)`. `out` is the absolute directory containing the completed site. `cfg` is the nbdev project configuration. The callback writes additional files into `out`; its return value is ignored. Callback errors fail the build. Without this setting, no callback runs.\n",
+    "\n",
+    "Author the callback in a notebook and export it before building the docs, as with custom processors. Its dependencies belong to the project's documentation setup."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6aea6659",
+   "metadata": {},
+   "source": [
+    "## Build configuration\n",
+    "\n",
+    "`octavo.yml` contains named settings, such as `title: Demo`, read by Octavo's `read_cfg`. An empty file selects Octavo’s defaults. A YAML list or a single value such as `false` cannot supply those settings.\n",
+    "\n",
+    "The build checks this file before running render scripts or notebook processors. Invalid configuration therefore fails before project code executes."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d6904375",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "def octavo_config(root):\n",
+    "    \"Settings from `octavo.yml`, as Octavo's `read_cfg` reads them; the file must exist\"\n",
+    "    if not (p := Path(root)/CFG_FILE).is_file(): raise FileNotFoundError(p)\n",
+    "    return read_cfg(root)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "87c206ca",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "with tempfile.TemporaryDirectory() as d:\n",
+    "    root = Path(d)\n",
+    "    test_fail(lambda: octavo_config(root), contains='octavo.yml')\n",
+    "    for text in ('- not a mapping', '[]', 'false', '0'):\n",
+    "        (root/'octavo.yml').write_text(text)\n",
+    "        test_fail(lambda: octavo_config(root), contains='mapping')\n",
+    "    (root/'octavo.yml').write_text('')\n",
+    "    test_eq(octavo_config(root), {})"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5407994a",
+   "metadata": {},
+   "source": [
+    "Links to this project’s API should stay within the website being built. For example, when building nbdev’s website, a generated link for `ModuleMaker` points to `/api/maker.html#modulemaker` rather than the published nbdev site.\n",
+    "\n",
+    "Links to dependencies still point to their published documentation. An absolute URL written by the author is not changed."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f6830357",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "def octavo_docs(\n",
+    "    path:str=None, # Path to the project or its notebooks\n",
+    "):\n",
+    "    \"Create Octavo docs and run the optional docs_post_build callback\"\n",
+    "    cfg = get_config(path)\n",
+    "    settings = {'output': cfg.doc_path, **octavo_config(cfg.nbs_path)}\n",
+    "    with working_directory(cfg.config_path):\n",
+    "        pages,files = script_pages(cfg.nbs_path, settings.get('exclude'))\n",
+    "        docs = scan(cfg.nbs_path, nbproc=OctavoProc(local_lib=local_libraries(cfg)), exclude=settings.get('exclude')) + pages\n",
+    "        site = Site(docs, root=cfg.nbs_path, files=files, **settings)\n",
+    "        if (miss := site.build()): print(miss)\n",
+    "        if (post := cfg.get('docs_post_build')):\n",
+    "            out = Path(site.settings['output']).expanduser()\n",
+    "            if not out.is_absolute(): out = cfg.nbs_path/out\n",
+    "            import_obj(post)(out.resolve(), cfg)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0d5735ac",
+   "metadata": {},
+   "source": [
+    "## Build a documentation site\n",
+    "\n",
+    "`nbdev-docs` reads `octavo.yml` and processes notebooks and render scripts together. It does not migrate sources or change `_quarto.yml`. This temporary project builds linked pages and generated assets, then demonstrates that invalid configuration is rejected before executing a render script."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7c8fa2af",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "15"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "build_tmp = tempfile.TemporaryDirectory()\n",
+    "project = Path(build_tmp.name)\n",
+    "nbs = project/'nbs'\n",
+    "nbs.mkdir()\n",
+    "(project/'pyproject.toml').write_text('[project]\\nname = \"demo\"\\n[tool.nbdev]\\nnbs_path = \"nbs\"\\nskip_procs = \"insert_warning\"\\n')\n",
+    "(nbs/'octavo.yml').write_text('title: Demo\\noutput: ../_octavo\\nsite-url: https://example.com\\n')\n",
+    "(nbs/'_quarto.yml').write_text('project:\\n  type: website\\n')\n",
+    "(nbs/'index.md').write_text('# Home\\n\\nRead the [guide](guide.ipynb).')\n",
+    "guide = new_nb([mk_cell('# Guide\\n\\n> A notebook page', 'markdown'), mk_cell('Notebook content.', 'markdown')])\n",
+    "write_nb(guide, nbs/'guide.ipynb')\n",
+    "(nbs/'generated.md.py').write_text('print(\"# Generated page\")')\n",
+    "(nbs/'image.svg.py').write_text('print(\"<svg/>\")')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f7e9a3f2",
+   "metadata": {},
+   "source": [
+    "The ordinary build command leaves Quarto configuration unchanged. Without `output` in `octavo.yml`, it uses nbdev’s project-relative `doc_path`. An explicit Octavo output takes precedence and is relative to the notebooks directory. Here, `../_octavo` overrides the default project-level `_docs` directory."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b5801459",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "with working_directory(project): run('nbdev-docs')\n",
+    "out = project/'_octavo'\n",
+    "assert 'guide.html' in (out/'index.html').read_text()\n",
+    "assert 'Notebook content.' in (out/'guide.html').read_text()\n",
+    "assert 'AUTOGENERATED' not in (out/'guide.md').read_text()\n",
+    "assert (out/'generated.html').exists()\n",
+    "test_eq((out/'image.svg').read_text(), '<svg/>\\n')\n",
+    "test_eq((nbs/'_quarto.yml').read_text(), 'project:\\n  type: website\\n')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "820a17f9",
+   "metadata": {},
+   "source": [
+    "Existing scripts can pass the default file-selection options explicitly. Octavo accepts those calls, but still builds the whole site. For normal use, run `nbdev-docs` without file-selection options."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bd46348b",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "/Users/rensdimmendaal/aai/ws/execnb/execnb/shell.py:172: UserWarning: Failed loading extension dialoghelper.bootstrap: Local skills already enabled for /Users/rensdimmendaal/aai/ws/nbdev/nbs/api\n",
+      "  for w in warns: warnings.warn(w)\n"
+     ]
+    }
+   ],
+   "source": [
+    "with working_directory(project): run(r'nbdev-docs --file-re \"\\.(?:ipynb|qmd|html)$\"')\n",
+    "nbdev_docs(project, file_glob=None)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "424b4dde",
+   "metadata": {},
+   "source": [
+    "The Octavo integration currently builds the whole site. Non-default file filters are rejected because selective builds are not implemented.\n",
+    "\n",
+    "Invalid configuration must fail before any render script runs."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "773d00ae",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "test_fail(lambda: nbdev_docs(project, file_glob='*.ipynb'), contains='file_glob')\n",
+    "(nbs/'octavo.yml').write_text('- invalid')\n",
+    "(nbs/'generated.md.py').write_text('raise RuntimeError(\"script ran before validation\")')\n",
+    "test_fail(lambda: nbdev_docs(project), contains='mapping')\n",
+    "build_tmp.cleanup()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5c1356ac",
+   "metadata": {},
+   "source": [
+    "## Local preview"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f568f1c6",
+   "metadata": {},
+   "source": [
+    "`nbdev-preview` builds and serves an Octavo site at `http://localhost:8000`. Use `--port`, `--host`, and `--no-browser` to change the server options. It watches the project for edits and rebuilds the whole site in a fresh process. Refresh the browser manually after each build.\n",
+    "\n",
+    "Preview writes directly to the configured documentation output, unlike Quarto’s separate preview cache. Pages can be unavailable during a rebuild. A failed build clears partial output and shows an error page; the server keeps watching so the next successful build restores the site. Errors appear in the terminal.\n",
+    "\n",
+    "Hidden paths, Python bytecode caches, and the output directory are ignored. Restart preview after changing the notebooks or output directory. Octavo always builds on startup; `--render` is redundant and `--n-workers` remains Quarto-only."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "db88c5c9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "def octavo_preview(\n",
+    "    path:str=None, # Path to the project or its notebooks\n",
+    "    port:int=None, # HTTP port (defaults to 8000)\n",
+    "    host:str=None, # Bind address (defaults to localhost)\n",
+    "    no_browser:bool=False, # Do not open a browser\n",
+    "):\n",
+    "    \"Serve documentation and rebuild when project files change\"\n",
+    "    cfg = get_config(path)\n",
+    "    root = cfg.config_path.resolve()\n",
+    "    settings = octavo_config(cfg.nbs_path)\n",
+    "    out = (cfg.nbs_path/Path(settings.get('output', cfg.doc_path)).expanduser()).resolve()\n",
+    "    if root.is_relative_to(out) or cfg.nbs_path.resolve().is_relative_to(out): raise ValueError('Output must not contain sources')\n",
+    "    changed = threading.Event()\n",
+    "\n",
+    "    def rebuild():\n",
+    "        try: subprocess.run(['nbdev-docs', '--path', str(root)], cwd=root, check=True)\n",
+    "        except subprocess.CalledProcessError:\n",
+    "            shutil.rmtree(out, ignore_errors=True)\n",
+    "            out.mkdir(parents=True, exist_ok=True)\n",
+    "            (out/'index.html').write_text('<h1>Build failed - see terminal</h1>')\n",
+    "            print('Build failed; waiting for another edit.', flush=True)\n",
+    "\n",
+    "    def on_change(event):\n",
+    "        if event.event_type not in ('created', 'modified', 'deleted', 'moved'): return\n",
+    "        if event.is_directory and event.event_type=='modified': return\n",
+    "        for name in (event.src_path, getattr(event, 'dest_path', '')):\n",
+    "            if not name: continue\n",
+    "            src = Path(name).resolve()\n",
+    "            if src.is_relative_to(out) or not src.is_relative_to(root): continue\n",
+    "            if any(p.startswith('.') or p=='__pycache__' for p in src.relative_to(root).parts): continue\n",
+    "            changed.set()\n",
+    "\n",
+    "    handler = partial(SimpleHTTPRequestHandler, directory=str(out))\n",
+    "    with ThreadingHTTPServer((host or 'localhost', 8000 if port is None else port), handler) as server:\n",
+    "        url = f'http://{host or \"localhost\"}:{server.server_port}'\n",
+    "        with fs_watchdog(on_change, root):\n",
+    "            rebuild()\n",
+    "            threading.Thread(target=server.serve_forever, daemon=True).start()\n",
+    "            try:\n",
+    "                print(f'{url} - refresh your browser after rebuilding', flush=True)\n",
+    "                if not no_browser: webbrowser.open(url)\n",
+    "                while True:\n",
+    "                    changed.wait()\n",
+    "                    changed.clear()\n",
+    "                    while changed.wait(0.2): changed.clear()\n",
+    "                    rebuild()\n",
+    "            finally: server.shutdown()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b53bd453",
+   "metadata": {},
+   "source": [
+    "## Repository Markdown"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "09b41c23",
+   "metadata": {},
+   "source": [
+    "`nbdev-readme` and `nbdev-contributing` render the configured notebooks to the project root without Quarto. They use stored outputs and do not execute ordinary code cells. nbdev processors still run, including custom processors and generated API documentation. Titles and descriptions become Markdown. Symbol links use published documentation URLs.\n",
+    "\n",
+    "Images stored in notebook outputs are extracted into a directory beside the generated Markdown. The directory uses the source notebook’s name: `index.ipynb` produces `index_files`, even though the generated document is named `README.md`. This matches nbdev’s Quarto convention.\n",
+    "\n",
+    "Authored relative links are copied unchanged; their destinations are not adjusted for the document’s new location.\n",
+    "\n",
+    "A missing source notebook is skipped. With `chk_time=True`, an existing document is skipped when its modification time is at least as recent as the source notebook’s."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0d38402b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "def octavo_readme(\n",
+    "    path:str=None, # Path to the project or its notebooks\n",
+    "    chk_time:bool=False, # Only build if the source is newer\n",
+    "    contributing:bool=False, # Render CONTRIBUTING instead of README\n",
+    "):\n",
+    "    \"Render a repository Markdown document from a notebook's stored outputs\"\n",
+    "    cfg = get_config(path)\n",
+    "    nbname = cfg.get('contributing_nb', 'contributing.ipynb') if contributing else cfg.readme_nb\n",
+    "    root = Path(path).absolute() if path else cfg.nbs_path\n",
+    "    src = root/nbname\n",
+    "    if not src.exists(): src = cfg.nbs_path/nbname\n",
+    "    if not src.exists(): return\n",
+    "    name = 'CONTRIBUTING' if contributing else 'README'\n",
+    "    dest = cfg.config_path/f'{name}.md'\n",
+    "    if chk_time and _doc_mtime_not_older(dest, src): return\n",
+    "    octavo_config(cfg.nbs_path)\n",
+    "    with working_directory(cfg.config_path):\n",
+    "        proc = OctavoProc(strip_libs=local_libraries(cfg))\n",
+    "        doc = md2doc(ipynb2md(src, nbproc=proc))\n",
+    "        head = f'# {doc.meta[\"title\"]}\\n\\n' if doc.meta.get('title') else ''\n",
+    "        if desc:=doc.meta.get('description'): head += f'{desc}\\n\\n'\n",
+    "        md2gfm(head + doc.body, dest=dest, imgdir=cfg.config_path/f'{src.stem}_files', raw=('md', 'html'))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f5e7d85b",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "2"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "readme_tmp = tempfile.TemporaryDirectory()\n",
+    "project = Path(readme_tmp.name)\n",
+    "nbs = project/'nbs'\n",
+    "nbs.mkdir()\n",
+    "(project/'pyproject.toml').write_text(r'''[project]\n",
+    "name = \"different-distribution\"\n",
+    "[project.entry-points.nbdev]\n",
+    "nbdev = \"nbdev._modidx:d\"\n",
+    "[tool.nbdev]\n",
+    "nbs_path = \"nbs\"\n",
+    "contributing_nb = \"help.ipynb\"\n",
+    "''')\n",
+    "(nbs/'octavo.yml').write_text('{}')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "85cd81cb",
+   "metadata": {},
+   "source": [
+    "README generation should use a notebook’s saved results without rerunning its ordinary code cells. The example below constructs a notebook containing a saved image and code that raises an exception if executed.\n",
+    "\n",
+    "Successful rendering must include the saved image without running that code. This matches Quarto’s `--no-execute` behaviour."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4b588547",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "png = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aX1sAAAAASUVORK5CYII='\n",
+    "image = mk_cell('#| echo: false\\nraise RuntimeError(\"must not execute\")')\n",
+    "image.outputs = [dict(output_type='display_data', metadata={}, data={'image/png': png})]\n",
+    "book = new_nb([mk_cell('# Example\\n\\n> Repository document', 'markdown'),\n",
+    "               mk_cell('Use `ModuleMaker`. [Guide](guide.md). [Reference][ref]\\n\\n[ref]: guide.md', 'markdown'),\n",
+    "               image, mk_cell('#| include: false\\n\"excluded cell\"')])\n",
+    "write_nb(book, nbs/'index.ipynb')\n",
+    "write_nb(book, nbs/'help.ipynb')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "36527ea0",
+   "metadata": {},
+   "source": [
+    "README and CONTRIBUTING use separate source notebooks and produce separate Markdown files. This test gives both notebooks identical content to check that both commands handle hidden code, saved images, and links consistently."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7b518cd0",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "/Users/rensdimmendaal/aai/ws/execnb/execnb/shell.py:172: UserWarning: Failed loading extension dialoghelper.bootstrap: Local skills already enabled for /Users/rensdimmendaal/aai/ws/nbdev/nbs/api\n",
+      "  for w in warns: warnings.warn(w)\n"
+     ]
+    }
+   ],
+   "source": [
+    "cwd = Path.cwd()\n",
+    "octavo_readme(project)\n",
+    "with working_directory(project):\n",
+    "    run('nbdev-readme')\n",
+    "    run('nbdev-contributing')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a1f61198",
+   "metadata": {},
+   "source": [
+    "A README is read in the repository, not alongside the generated API pages. Its generated symbol links therefore point to published documentation—even when they refer to this project’s own API.\n",
+    "\n",
+    "For example, nbdev’s README links `ModuleMaker` to the published nbdev website. The nbdev website itself uses a local API link. This difference depends on where the document will be read, not on which library the symbol belongs to."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "94428a10",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "for name,stem in (('README', 'index'), ('CONTRIBUTING', 'help')):\n",
+    "    text = (project/f'{name}.md').read_text()\n",
+    "    assert '# Example' in text and 'Repository document' in text\n",
+    "    assert 'https://nbdev.fast.ai/api/maker.html#modulemaker' in text\n",
+    "    assert '(guide.md)' in text and '[ref]: guide.md' in text\n",
+    "    assert 'must not execute' not in text and 'excluded cell' not in text\n",
+    "    assert 'data:image' not in text and f'{stem}_files/' in text\n",
+    "    assert list((project/f'{stem}_files').glob('*.png'))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5dc6d9c7",
+   "metadata": {},
+   "source": [
+    "An up-to-date README should not be rewritten. Projects without a CONTRIBUTING source should still build their other documents."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c7cd1ddd",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "before = (project/'README.md').stat().st_mtime_ns\n",
+    "octavo_readme(project, chk_time=True)\n",
+    "test_eq((project/'README.md').stat().st_mtime_ns, before)\n",
+    "assert not (nbs/'_quarto.yml').exists()\n",
+    "(nbs/'help.ipynb').unlink()\n",
+    "octavo_readme(project, contributing=True)\n",
+    "readme_tmp.cleanup()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c4466973",
+   "metadata": {},
+   "source": [
+    "## Source migration"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b6ef5093",
+   "metadata": {},
+   "source": [
+    "`nbdev-migrate-octavo` converts Quarto documentation sources in place. Commit or back up the project before running it. The command:\n",
+    "\n",
+    "1. Renames `.qmd` documents to `.md` and `.qmd.py` render scripts to `.md.py`.\n",
+    "2. Rewrites references to renamed documents, and to Markdown copies of pages: Quarto named the copy of `page.ipynb` `page.html.md`, while Octavo names it `page.md`. This includes plain-text files such as `llms.txt`.\n",
+    "3. Replaces Quarto content-visible block markers with raw-format fences.\n",
+    "4. Moves `subtitle` page metadata to `description`. Octavo reads Quarto's other metadata names as they are.\n",
+    "5. Creates `octavo.yml` from selected Quarto settings when no Octavo configuration exists.\n",
+    "6. Reports the page and site settings that Octavo has no equivalent for.\n",
+    "7. Leaves `_quarto.yml` unchanged for reference.\n",
+    "\n",
+    "The presence of `octavo.yml` selects Octavo.\n",
+    "\n",
+    "Migration converts sources and configuration, not the site’s design. CSS, layouts, and themes need project-specific review. Stylesheet files remain unchanged, and of Quarto’s `page-layout` values Octavo supports only `custom`. Quarto stylesheet references are not copied into `octavo.yml`."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "020e0e90",
+   "metadata": {},
+   "source": [
+    "The source conversions and unsupported-setting reports live in `octavo.migrate`. nbdev owns render-script discovery, renaming and YAML-docstring conversion, and supplies project configuration, the output directory override, custom-sidebar selection, and its accepted metadata keys. The examples below exercise that integration."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "47b0e5d9",
+   "metadata": {},
+   "source": [
+    "Configuration is parsed before any source files are changed. Empty YAML uses defaults; a scalar or list cannot represent site settings."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "deb7ee06",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "def _quarto_config(nbs_path): return read_quarto_config(nbs_path/'_quarto.yml'),read_quarto_config(nbs_path/'nbdev.yml')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "083e9cb7",
+   "metadata": {},
+   "source": [
+    "nbdev already knows where to put the website through `doc_path`, relative to the project root. Migration leaves `output` out of `octavo.yml` when that destination is sufficient.\n",
+    "\n",
+    "An explicit Quarto `output-dir` can name a different destination. Migration preserves that override, expressing it relative to the notebooks directory for Octavo. For example, a project-level `website` directory becomes `../website` when notebooks live in `nbs`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "127739bd",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "def _octavo_output(nbs_path, qy, ny):\n",
+    "    \"Return a Quarto output override relative to notebooks, or None when doc_path suffices\"\n",
+    "    out_dir = (ny.get('project', {}) or {}).get('output-dir') or (qy.get('project', {}) or {}).get('output-dir')\n",
+    "    if not out_dir: return\n",
+    "    cfg = get_config(nbs_path)\n",
+    "    out_dir = (cfg.config_path/Path(out_dir).expanduser()).resolve()\n",
+    "    if out_dir == cfg.doc_path.resolve(): return\n",
+    "    return os.path.relpath(out_dir, Path(nbs_path).resolve()).replace(os.sep, '/')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6d3b3ba1",
+   "metadata": {},
+   "source": [
+    "Octavo derives its sidebar from directories, which matches the sidebar nbdev generates. A project with `custom_sidebar` writes `sidebar.yml` by hand instead, often grouping pages from one directory into sections. Migration converts that file into `sidebar-links`: pages become links and sections become groups. Entries without text take the page's title at build time. Quarto's `auto` entries and glob patterns have no Octavo equivalent; migration reports and omits them."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e0912069",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "def _octavo_sidebar(nbs_path):\n",
+    "    \"Convert the project's custom sidebar when enabled\"\n",
+    "    p = Path(nbs_path)/'sidebar.yml'\n",
+    "    if not get_config(nbs_path).custom_sidebar or not p.exists(): return {}\n",
+    "    sb = nested_idx(yaml.safe_load(p.read_text()) or {}, 'website', 'sidebar') or {}\n",
+    "    return quarto_sidebar(sb, p)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e1cd81ec",
+   "metadata": {},
+   "source": [
+    "Octavo uses Quarto's names and meanings for the settings the two share, but keeps them in one flat `octavo.yml`, where Quarto nests them under `website` and `format: html`. `_create_octavo_cfg` copies those settings across, converts the navigation bar and a hand-written sidebar, and prints the other Quarto settings, which Octavo has no equivalent for. An output override is included only when the Quarto destination differs from nbdev’s `doc_path`. The migration command writes the result to `octavo.yml` only when that file does not already exist.\n",
+    "\n",
+    "This is not a complete translation of Quarto configuration. The reported settings still need manual review."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2f2d4b3b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "def _create_octavo_cfg(nbs_path):\n",
+    "    \"Convert Quarto settings with nbdev's overlay, output path and custom sidebar\"\n",
+    "    nbs_path = Path(nbs_path).resolve()\n",
+    "    qy,ny = _quarto_config(nbs_path)\n",
+    "    output = _octavo_output(nbs_path, qy, ny)\n",
+    "    cfg = quarto_config(qy, nbs_path, overrides=ny) | _octavo_sidebar(nbs_path)\n",
+    "    if output is not None: cfg['output'] = output\n",
+    "    return cfg"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d884ea8b",
+   "metadata": {},
+   "source": [
+    "Render scripts keep their executable body. Only the leading YAML docstring needs the same metadata conversion as a document."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5927e211",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "_script_fm = re.compile(r'\\A(?P<q>\"{3}|\\'{3})---\\n(?P<fm>.*?)\\n---(?P=q)', re.DOTALL)\n",
+    "\n",
+    "def _script_md(m):\n",
+    "    \"Frontmatter block from a `_script_fm` match on a render script\"\n",
+    "    return f\"---\\n{m.group('fm')}\\n---\\n\"\n",
+    "\n",
+    "def repl_script_frontmatter_keys(s):\n",
+    "    \"Normalize a render script's leading YAML docstring for Octavo\"\n",
+    "    if not (m := _script_fm.match(s)): return s\n",
+    "    old = _script_md(m)\n",
+    "    new = repl_frontmatter_keys(old)\n",
+    "    if new == old: return s\n",
+    "    return m.group('q') + new.rstrip('\\n') + m.group('q') + s[m.end():]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "af51d9b8",
+   "metadata": {},
+   "source": [
+    "Switching builders requires source changes as well as new configuration: renamed documents need updated links, and Quarto-specific markup needs conversion. Migration checks rename conflicts and configuration before editing, preserves an existing `octavo.yml`, and retains `_quarto.yml` for comparison. Changes are made in place without automatic rollback, so commit or back up the project first."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c4b4478c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "NBDEV_KEYS = {'skip_exec', 'skip_showdoc'}\n",
+    "\n",
+    "def _migrate_octavo(path):\n",
+    "    \"Migrate documents and nbdev render scripts using the project's configuration\"\n",
+    "    path = Path(path).expanduser()\n",
+    "    scripts = source_files(path).map(lambda o: path/o).filter(lambda p: p.name.endswith('.qmd.py'))\n",
+    "    script_moves = {p:p.with_name(p.name.removesuffix('.qmd.py')+'.md.py') for p in scripts}\n",
+    "    moves = migrate_quarto(path, config=_create_octavo_cfg, extra_keys=NBDEV_KEYS, extra_moves=script_moves)\n",
+    "    for p in script_moves.values():\n",
+    "        migrate_md_file(p, [repl_script_frontmatter_keys])\n",
+    "        if m := _script_fm.match(p.read_text()):\n",
+    "            report_page_keys(p, extra_keys=NBDEV_KEYS, metadata=frontmatter(_script_md(m))[0])\n",
+    "    return moves"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5c6ac577",
+   "metadata": {},
+   "source": [
+    "A destination collision must stop migration before an existing file can be overwritten."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4134c362",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "with tempfile.TemporaryDirectory() as d:\n",
+    "    p = Path(d)\n",
+    "    (p/'page.qmd.py').touch()\n",
+    "    (p/'page.md.py').touch()\n",
+    "    with expect_fail(FileExistsError, contains='page.md.py'): _migrate_octavo(p)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ed43ff9d",
+   "metadata": {},
+   "source": [
+    "The default comes from the project configuration, so the command also works when notebooks live outside `nbs`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e332ece4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "@call_parse\n",
+    "def nbdev_migrate_octavo(\n",
+    "    path:str=None, # Documentation directory (defaults to configured nbs_path)\n",
+    "):\n",
+    "    \"Migrate Quarto-era nbdev project to Octavo\"\n",
+    "    moves = _migrate_octavo(get_config().nbs_path if path is None else path)\n",
+    "    for old,new in moves.items(): print(f'{old} -> {new}')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "65ed915c",
+   "metadata": {},
+   "source": [
+    "A documentation project can mix written pages, notebooks, and pages generated by Python scripts. The following project includes all three. After migration, we inspect their filenames, metadata, links, and retained content."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "08610b6b",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "52"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "migration_tmp = tempfile.TemporaryDirectory()\n",
+    "d = migration_tmp.name\n",
+    "nbs = Path(d)/'nbs'\n",
+    "(Path(d)/'pyproject.toml').write_text('[project]\\nname = \"demo\"\\n[tool.nbdev]\\nnbs_path = \"nbs\"\\ncustom_sidebar = true\\n')\n",
+    "(nbs/'blog/posts').mkdir(parents=True)\n",
+    "(nbs/'images').mkdir()\n",
+    "(nbs/'guide.qmd').write_text(r'''---\n",
+    "subtitle: A handy guide\n",
+    "toc-depth: 2\n",
+    "custom-key: keep-this\n",
+    "---\n",
+    "\n",
+    "See [blog](blog/index.qmd). The `.qmd` format is mentioned here.\n",
+    "\n",
+    "::: {.content-visible when-format=\"html\" style=\"text-align: center\"}\n",
+    "<iframe src=\"video\"></iframe>\n",
+    ":::\n",
+    "''')\n",
+    "(nbs/'blog/index.qmd').write_text(r'''---\n",
+    "title: Blog\n",
+    "subtitle: All posts\n",
+    "sidebar: false\n",
+    "listing:\n",
+    "  categories: true\n",
+    "---\n",
+    "\n",
+    "Back to [guide](../guide.qmd).\n",
+    "''')\n",
+    "(nbs/'llms.txt').write_text('- [API](api.html.md): reference\\n- [Guide](guide.md)\\n')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "866b1842",
+   "metadata": {},
+   "source": [
+    "Render scripts carry metadata in a Python docstring. Their program body and non-Markdown generated assets must remain unchanged."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "299d527a",
+   "metadata": {},
+   "source": [
+    "Only `.qmd.py` scripts need migration to `.md.py`. Existing `.md.py` pages and other double-suffix generators, such as `.svg.py` and `.html.py`, keep their filenames and contents. Ordinary `.py` files are unchanged too."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "759a5b2f",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "30"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "(nbs/'index.qmd.py').write_text(r'''\"\"\"---\n",
+    "title: Home\n",
+    "subtitle: Write, test, document, and distribute software packages and technical articles — all in one place, your notebook.\n",
+    "page-layout: custom\n",
+    "toc: false\n",
+    "---\"\"\"\n",
+    "print(\"# Home\")\n",
+    "''')\n",
+    "(nbs/'blog/posts/render.qmd.py').write_text('\"\"\"---\\ntitle: Rendered\\ntoc-depth: 3\\n---\"\"\"\\nprint(\"# Rendered\")\\n')\n",
+    "(nbs/'images/circles.svg.py').write_text('\"\"\"---\\n---\"\"\"\\nprint(\"<svg/>\")\\n')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d6815332",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "for name in ('existing.md.py', 'images/widget.html.py', 'ordinary.py'):\n",
+    "    (nbs/name).write_text('raise RuntimeError(\"migration must not execute scripts\")\\n')\n",
+    "script_before = {p:p.read_text() for p in nbs.rglob('*.py')}"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "57b7b6dd",
+   "metadata": {},
+   "source": [
+    "This project includes both supported and unsupported navbar icons. Migration should report the unsupported entry without losing the supported links. The project sets `custom_sidebar`, and its hand-written `sidebar.yml` has a section and an `auto` entry, which migration reports."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "58b0450c",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "163"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "(nbs/'_quarto.yml').write_text(r'''website:\n",
+    "  title: demo\n",
+    "  favicon: favicon.png\n",
+    "  description: A demo site\n",
+    "  open-graph: true\n",
+    "  twitter-card:\n",
+    "    site: \"@demo\"\n",
+    "    image: https://x.y/card.png\n",
+    "    image-width: 1200\n",
+    "  navbar:\n",
+    "    left:\n",
+    "      - text: Guide\n",
+    "        href: guide.qmd\n",
+    "    right:\n",
+    "      - icon: github\n",
+    "        href: https://github.com/x/y\n",
+    "      - icon: twitter\n",
+    "        href: https://twitter.com/x\n",
+    "        aria-label: Follow us\n",
+    "      - icon: bug\n",
+    "        href: https://x.y/issues\n",
+    "format:\n",
+    "  html:\n",
+    "    css: styles.css\n",
+    "    toc-depth: 4\n",
+    "''')\n",
+    "(nbs/'styles.css').write_text('body { color: red; }')\n",
+    "(nbs/'sidebar.yml').write_text(r'''website:\n",
+    "  sidebar:\n",
+    "    contents:\n",
+    "      - guide.qmd\n",
+    "      - section: More\n",
+    "        contents:\n",
+    "          - blog/index.qmd\n",
+    "          - 01_extra.ipynb\n",
+    "          - auto\n",
+    "''')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cb1a6d7c",
+   "metadata": {},
+   "source": [
+    "Notebook frontmatter and format-specific Markdown need the same conversion as standalone documents. Most notebooks have no frontmatter at all, such as `api.ipynb` here."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "add75676",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "nb = new_nb([mk_cell(r'''---\n",
+    "summary: Notebook summary\n",
+    "categories: [tutorial]\n",
+    "toc-depth: 2\n",
+    "---\n",
+    "\n",
+    "[guide](guide.qmd) and [blog](blog/index.qmd)\n",
+    "\n",
+    "::: {.content-visible when-format=\"markdown\"}\n",
+    "![CI](badge.svg)\n",
+    ":::''', 'markdown')])\n",
+    "write_nb(nb, nbs/'index.ipynb')\n",
+    "write_nb(new_nb([mk_cell('# API\\n\\nSee the [guide](guide.qmd).', 'markdown')]), nbs/'api.ipynb')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c7ab0d32",
+   "metadata": {},
+   "source": [
+    "Renaming includes nested documents and Markdown render scripts. Other generated asset types retain their filenames and content."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ff857ee9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "quarto_before = (nbs/'_quarto.yml').read_bytes()\n",
+    "with redirect_stdout(StringIO()) as out: moves = _migrate_octavo(nbs)\n",
+    "test_eq({str(k.relative_to(nbs)):str(v.relative_to(nbs)) for k,v in moves.items()}, {\n",
+    "    'blog/index.qmd':'blog/index.md', 'blog/posts/render.qmd.py':'blog/posts/render.md.py',\n",
+    "    'guide.qmd':'guide.md', 'index.qmd.py':'index.md.py'})\n",
+    "assert not (nbs/'guide.qmd').exists() and (nbs/'guide.md').exists()\n",
+    "assert not (nbs/'blog/index.qmd').exists() and (nbs/'blog/index.md').exists()\n",
+    "assert not (nbs/'index.qmd.py').exists() and (nbs/'index.md.py').exists()\n",
+    "assert not (nbs/'blog/posts/render.qmd.py').exists() and (nbs/'blog/posts/render.md.py').exists()\n",
+    "test_eq((nbs/'images/circles.svg.py').read_text(), '\"\"\"---\\n---\"\"\"\\nprint(\"<svg/>\")\\n')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "97b322f3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "for old,text in script_before.items():\n",
+    "    new = moves.get(old, old)\n",
+    "    actual = new.read_text()\n",
+    "    if old not in moves: test_eq(actual, text)\n",
+    "    else: test_eq(actual[_script_fm.match(actual).end():], text[_script_fm.match(text).end():])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0a8eb0af",
+   "metadata": {},
+   "source": [
+    "Render script metadata keeps Quarto's names, such as `page-layout` and `toc`, which Octavo reads as they are. Its `subtitle` becomes the description, and a long description must survive YAML serialization without inserted line continuations."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d2132c8f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "idx_txt = (nbs/'index.md.py').read_text()\n",
+    "idx_fm = frontmatter(_script_md(_script_fm.match(idx_txt)))[0]\n",
+    "test_eq(idx_fm['page-layout'], 'custom')\n",
+    "test_eq(idx_fm['toc'], False)\n",
+    "assert 'subtitle' not in idx_fm and '— all in one place' in idx_fm['description']\n",
+    "assert 'technical\\\\\\n' not in idx_txt"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cacaa706",
+   "metadata": {},
+   "source": [
+    "The converted configuration retains the site identity and supported navigation. The sidebar keeps its order and section; `01_extra.ipynb` links to its published name, `extra.html`. The site description, Open Graph and Twitter card settings, and `toc-depth`, carry over unchanged. It sets `math: dollars`, so `$…$` stays inline maths as in Quarto. Quarto CSS is not enabled in `octavo.yml`. The original configuration and stylesheet remain unchanged for manual adaptation."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b203a171",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "test_eq((nbs/'_quarto.yml').read_bytes(), quarto_before)\n",
+    "assert (nbs/'octavo.yml').exists()\n",
+    "cfg = yaml.safe_load((nbs/'octavo.yml').read_text())\n",
+    "test_eq(cfg['title'], 'demo')\n",
+    "test_eq(cfg['math'], 'dollars')\n",
+    "test_eq(cfg['description'], 'A demo site')\n",
+    "test_eq(cfg['open-graph'], True)\n",
+    "test_eq(cfg['twitter-card'], {'site': '@demo', 'image': 'https://x.y/card.png', 'image-width': 1200})\n",
+    "assert 'output' not in cfg\n",
+    "test_eq(cfg['toc-depth'], 4)\n",
+    "assert 'css' not in cfg\n",
+    "test_eq((nbs/'styles.css').read_text(), 'body { color: red; }')\n",
+    "test_eq(cfg['favicon'], 'favicon.png')\n",
+    "test_eq(cfg['nav-links'], [{'text': 'Guide', 'href': 'guide.html'}])\n",
+    "test_eq(cfg['tools'], [{'icon': 'github', 'href': 'https://github.com/x/y', 'label': 'GitHub'},\n",
+    "                       {'icon': 'x', 'href': 'https://twitter.com/x', 'label': 'Follow us'}])\n",
+    "test_eq(cfg['sidebar-links'], [{'href': 'guide.html'},\n",
+    "                               {'text': 'More', 'children': [{'href': 'blog/index.html'}, {'href': 'extra.html'}]}])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1fb80c14",
+   "metadata": {},
+   "source": [
+    "Migration printed what Octavo will ignore, for manual review: Quarto's stylesheet setting, the unbundled icon and the `auto` sidebar entry, the guide's `custom-key`, the blog listing's `categories` filter option:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8529b5d9",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "/private/var/folders/0h/5ktbjhg17ns6j8zgdsgvzvy80000gn/T/tmp26a6l0uo/nbs/octavo.yml: dropped tool icon 'bug' (https://x.y/issues): not bundled by octavo. Add it back with `icon: <path-or-url>` to your own SVG.\n",
+      "/private/var/folders/0h/5ktbjhg17ns6j8zgdsgvzvy80000gn/T/tmp26a6l0uo/nbs: Octavo has no equivalent for format.html.css\n",
+      "/private/var/folders/0h/5ktbjhg17ns6j8zgdsgvzvy80000gn/T/tmp26a6l0uo/nbs/sidebar.yml: dropped sidebar entry 'auto': Octavo has no equivalent. List those pages explicitly.\n",
+      "/var/folders/0h/5ktbjhg17ns6j8zgdsgvzvy80000gn/T/tmp26a6l0uo/nbs/blog/index.md: Octavo ignores listing.categories\n",
+      "/var/folders/0h/5ktbjhg17ns6j8zgdsgvzvy80000gn/T/tmp26a6l0uo/nbs/guide.md: Octavo ignores custom-key\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "report = out.getvalue()\n",
+    "assert 'format.html.css' in report and \"'bug'\" in report and \"'auto'\" in report\n",
+    "assert f\"{nbs/'guide.md'}: Octavo ignores custom-key\" in report\n",
+    "assert f\"{nbs/'blog/index.md'}: Octavo ignores listing.categories\" in report\n",
+    "print(report)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6e3e0a03",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "<_io.StringIO>"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "out"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "de7fa745",
+   "metadata": {},
+   "source": [
+    "Frontmatter aliases change at the top level. Relative links still need to reach the renamed document from its own directory, and `llms.txt` now links Octavo's Markdown copies."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "958eb45c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "guide_fm,guide_body = frontmatter((nbs/'guide.md').read_text())\n",
+    "test_eq(guide_fm['description'], 'A handy guide')\n",
+    "assert 'subtitle' not in guide_fm\n",
+    "test_eq(guide_fm['toc-depth'], 2)\n",
+    "test_eq(guide_fm['custom-key'], 'keep-this')\n",
+    "\n",
+    "blog_fm,blog_body = frontmatter((nbs/'blog/index.md').read_text())\n",
+    "test_eq(blog_fm['description'], 'All posts')\n",
+    "test_eq(blog_fm['sidebar'], False)\n",
+    "test_eq(blog_body.strip(), 'Back to [guide](../guide.md).')\n",
+    "test_eq((nbs/'llms.txt').read_text(), '- [API](api.md): reference\\n- [Guide](guide.md)\\n')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "838adac0",
+   "metadata": {},
+   "source": [
+    "Notebook Markdown receives the same metadata conversion. A second migration must leave the converted metadata unchanged."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4a823abd",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "/var/folders/0h/5ktbjhg17ns6j8zgdsgvzvy80000gn/T/tmp26a6l0uo/nbs/blog/index.md: Octavo ignores listing.categories\n",
+      "/var/folders/0h/5ktbjhg17ns6j8zgdsgvzvy80000gn/T/tmp26a6l0uo/nbs/guide.md: Octavo ignores custom-key\n"
+     ]
+    }
+   ],
+   "source": [
+    "nb_fm,nb_body = frontmatter(read_nb(nbs/'index.ipynb').cells[0].source)\n",
+    "test_eq(nb_fm['description'], 'Notebook summary')\n",
+    "test_eq(nb_fm['categories'], ['tutorial'])\n",
+    "assert 'summary' not in nb_fm\n",
+    "test_eq(nb_fm['toc-depth'], 2)\n",
+    "\n",
+    "test_eq(_migrate_octavo(nbs), {})\n",
+    "test_eq(frontmatter((nbs/'guide.md').read_text())[0], guide_fm)\n",
+    "migration_tmp.cleanup()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "09076322",
+   "metadata": {},
+   "source": [
+    "This project keeps notebooks in `docs/notebooks` and sets `doc_path` to `public`. Migration omits redundant output settings; the build still writes to the project’s `public` directory. A different Quarto destination is preserved."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d27559e2",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "7"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "nested_tmp = tempfile.TemporaryDirectory()\n",
+    "d = nested_tmp.name\n",
+    "project = Path(d)\n",
+    "nbs = project/'docs/notebooks'\n",
+    "nbs.mkdir(parents=True)\n",
+    "(project/'pyproject.toml').write_text('[project]\\nname = \"demo\"\\n[tool.nbdev]\\nnbs_path = \"docs/notebooks\"\\ndoc_path = \"public\"\\n')\n",
+    "(nbs/'_quarto.yml').write_text('website:\\n  title: Demo\\nformat:\\n  html:\\n    toc: false\\n')\n",
+    "(nbs/'guide.qmd').write_text('# Guide')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e4a5d888",
+   "metadata": {},
+   "source": [
+    "A project with nested notebooks should still publish to its configured project-level output directory. The installed CLI must find that directory without a `--path` override.\n",
+    "\n",
+    "Migration does not invent footer text. A project must supply its own footer."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "07930509",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "with working_directory(project): run('nbdev-migrate-octavo')\n",
+    "settings = octavo_config(nbs)\n",
+    "assert 'output' not in settings\n",
+    "test_eq(settings['toc'], False)\n",
+    "assert 'footer' not in settings\n",
+    "assert (nbs/'guide.md').exists() and (nbs/'_quarto.yml').exists()\n",
+    "with working_directory(project): run('nbdev-docs')\n",
+    "assert (project/'public/guide.html').exists()\n",
+    "\n",
+    "test_eq(_octavo_output(nbs, {'project': {'output-dir': 'public'}}, {}), None)\n",
+    "test_eq(_octavo_output(nbs, {'project': {'output-dir': 'website'}}, {}), '../../website')\n",
+    "test_eq(_octavo_output(nbs, {'project': {'output-dir': 'website'}}, {'project': {'output-dir': 'public'}}), None)\n",
+    "test_eq(_octavo_output(nbs, {'project': {'output-dir': str(project/'elsewhere')}}, {}), '../../elsewhere')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "41760705",
+   "metadata": {},
+   "source": [
+    "An existing Octavo configuration belongs to the author. Repeating migration must preserve it rather than regenerate defaults."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f3a656bf",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "before = (nbs/'octavo.yml').read_text()\n",
+    "test_eq(_migrate_octavo(nbs), {})\n",
+    "test_eq((nbs/'octavo.yml').read_text(), before)\n",
+    "nested_tmp.cleanup()"
+   ]
+  }
+ ],
+ "metadata": {
+  "solveit": {
+   "default_code": true,
+   "mode": "learning",
+   "use_thinking": false,
+   "use_tools": true,
+   "ver": 2
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/pyproject.toml b/pyproject.toml
index 3ffacb753..86c459ea2 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -22,7 +22,8 @@ dependencies = [ "fastcore>=2.2.28", "execnb>=0.3.3", "astunparse", "ghapi>=2.0.
     "setuptools", "build", "fastgit>=0.0.7", "pyyaml", "tomli; python_version < '3.11'", ]
 
 [project.optional-dependencies]
-dev = [ "ipywidgets", "nbdev-numpy", "nbdev-stdlib", "pandas", "matplotlib", "black", "svg.py", "pysym2md>=0.0.6", "llms-txt", "sphinx", "plum-dispatch", "nbclient", "ipykernel", ]
+octavo = ["aai-octavo>=0.0.4"]
+dev = [ "ipywidgets", "nbdev-numpy", "nbdev-stdlib", "pandas", "matplotlib", "black", "svg.py", "pysym2md>=0.0.6", "llms-txt", "sphinx", "plum-dispatch", "nbclient", "ipykernel", "aai-octavo>=0.0.4", ]
 
 [project.urls]
 Repository = "https://github.com/AnswerDotAI/nbdev"
@@ -46,6 +47,7 @@ nbdev-test = "nbdev.test:nbdev_test"
 nbdev-new = "nbdev.cli:nbdev_new"
 nbdev-migrate = "nbdev.migrate:nbdev_migrate"
 nbdev-migrate-config = "nbdev.migrate:nbdev_migrate_config"
+nbdev-migrate-octavo = "nbdev.octavo:nbdev_migrate_octavo"
 nbdev-install-quarto = "nbdev.quarto:install_quarto"
 nbdev-install = "nbdev.quarto:install"
 nbdev-docs = "nbdev.quarto:nbdev_docs"