# Docs Explorer

Local-only web UI for browsing every markdown doc in this repo:
`PUBLIC_API`, the standards, the recipes, internal docs, the
example READMEs, `CHANGELOG`, `FEEDBACK` — all in one navigable
interface with full-text search and clean rendering.

For maintainers, contributors, and engineering managers.

## Run it

```bash
python tools/docs_explorer/serve.py
```

Opens `http://127.0.0.1:8765/` in your default browser. Press
`Ctrl+C` to stop.

Options:

```bash
python tools/docs_explorer/serve.py --port 9000     # different port
python tools/docs_explorer/serve.py --no-open       # don't auto-open browser
```

## What you get

- **Sidebar** — every markdown file in the repo, grouped by
  category (Public API, Standards, Recipes, Internal, Examples,
  Project meta, etc.) and ordered sensibly within each group.
- **Search** — `Ctrl+K` (or `Cmd+K`) focuses the search box;
  full-text substring match across every doc with snippet
  highlighting; arrow keys to navigate, Enter to jump.
- **Markdown rendering** — GFM tables, fenced code blocks with
  syntax highlighting (Prism.js), heading anchors.
- **Cross-doc links** — relative `[link](path/to/other.md)`
  navigates within the SPA; `[external](https://...)` opens in
  a new tab.
- **Table of contents** — right-rail TOC built from H2/H3
  headings, with scroll-spy highlighting the current section.
- **Copy buttons** — every code block gets a "Copy" button on
  hover.
- **Shareable URLs** — `#/docs/standards/RELEASING.md` is a
  bookmarkable URL; the back button works.

## Constraints

- **Stdlib only.** No `pip install` required, no `node_modules`,
  no build step. Markdown rendering and syntax highlighting use
  CDN-hosted libraries (cached after first load).
- **127.0.0.1 only.** Never binds to `0.0.0.0`. Not designed to
  be exposed to a network.
- **Not in the published wheel.** Lives under `tools/`, which the
  wheel build (`packages = ["src/mgf"]`) excludes by construction.
  Verified: this directory does NOT appear in
  `mgf/common/_standards/` or anywhere else in the wheel artifact.

## Limitations (intentional, for the MVP)

- **No runnable examples.** Code blocks are display-only. (If
  the demand surfaces, a `/api/run` subprocess sandbox endpoint
  is the natural next step.)
- **No auto-generated API explorer.** `PUBLIC_API.md` is rendered
  as-is; no per-symbol introspection of `mgf.common.*`. (Same:
  add later if useful.)
- **No persistent state.** No favorites, no recent-visited, no
  notes. The browser's history + bookmarks cover this.

## Where this fits

- **`PUBLIC_API.md`** is the contract (always machine-readable
  via `PUBLIC_API.json`).
- **`docs/standards/`** is the ground truth for cross-project
  policies.
- **This tool** is just a faster way to read all of the above
  without grepping the filesystem or remembering paths.

It's a reading tool, not a publishing tool. If you want to
publish docs externally (Codeberg Pages, ReadTheDocs), use
`mkdocs-material` against the same source files — this tool
doesn't replace that.
