# Guidedog

{download}`English <_static/repository/README.md>` · {download}`简体中文 <_static/repository/README.zh-CN.md>` · {download}`日本語 <_static/repository/README.ja.md>` · {download}`한국어 <_static/repository/README.ko.md>` · {download}`हिन्दी <_static/repository/README.hi.md>` · {download}`Español <_static/repository/README.es.md>` · {download}`Deutsch <_static/repository/README.de.md>`

**Write once. Explain well. Publish on the web and on paper.**

Guidedog builds HTML documentation sites and PDF books from reStructuredText and Markdown. It is written in Odin. Its conversion engine is **Guidedoc**, and Typst typesets the PDF pages. No Python environment or LaTeX installation is needed.

Sphinx inspires the authoring workflow. Guidedog is an independent system: configuration is declarative TOML, API extraction is static, and Python configuration and extensions are never executed. Complete Sphinx compatibility is not a goal.

## Start a project

```sh
guidedog quickstart docs
guidedog build html docs
guidedog build pdf docs
guidedog serve docs
```

The project contains `conf.toml`, `index.rst`, `_templates/layout.html`, `_templates/book.typ`, and `_static/`. Templates are ordinary files you can edit. HTML provides navigation, search, code highlighting, diagrams, and equations. PDF books provide chapters, cross-references, figures, indexes, and language-aware typesetting.

The default theme is light. Readers can choose dark or the system theme. The manual detects the browser language on its landing page and repository overview. A saved choice takes precedence; direct links to an edition or chapter remain explicit requests.

```sh
guidedog convert notes.md --to pdf --output notes.pdf
guidedog clean docs
guidedog migrate conf.py
```

## Install

Each [release](https://github.com/insanai/guidedog/releases) has an archive for Linux (x86-64 and ARM64), macOS (Apple silicon and Intel), and Windows (x86-64). Each archive carries Typst, Graphviz, and tree-sitter, so building sites and books needs nothing else installed. Linux needs glibc 2.35 or later and libcurl; macOS needs version 12 or later. Download the archive for your system and `SHA256SUMS`, then check and install it:

```sh
sha256sum -c --ignore-missing SHA256SUMS      # on macOS: shasum -a 256 -c --ignore-missing SHA256SUMS
tar -xzf guidedog-linux-amd64.tar.gz
sudo install guidedog-linux-amd64/guidedog /usr/local/bin/
```

On macOS, install from the official [Guidedog Homebrew tap](https://github.com/insanai/homebrew-guidedog). Homebrew selects the Apple silicon or Intel archive. The tap also supports Linux:

```sh
brew tap insanai/guidedog
brew install insanai/guidedog/guidedog
guidedog --version
```

On Windows, unzip the archive and add its folder to `PATH`; keep the Graphviz DLLs and `config8` beside `guidedog.exe`. The programs are not code-signed: on macOS, remove the quarantine from a browser download with `xattr -d com.apple.quarantine guidedog`. The release notes describe each platform's limits.

## Build from source

Install Odin `dev-2026-10` (`tools/install-toolchain.sh odin DIR` fetches and checks it), a C compiler, and on Linux the libcurl, expat, and zlib development packages. Build the native libraries, then Guidedog:

```sh
native/tree-sitter/build.sh
native/graphviz/build.sh
tools/release/build.sh
```

`build/guidedog` then uses an installed Typst 0.15.1 for PDF. To embed the Typst compiler as the releases do, install Rust and Cargo and run:

```sh
native/typst_bridge/build.sh
tools/release/build.sh --release --typst-bridge
```

On Windows, use Git Bash with Visual Studio's C++ tools and LLVM. Graphviz has no static Windows build, so run `native/graphviz/windows.sh` instead of `build.sh`: it installs the official Graphviz 16.1.0 DLLs, which `tools/release/build.sh` copies beside `build/guidedog.exe`. `tools/release/suites.sh` runs the test suites, and [RELEASING.md](https://github.com/insanai/guidedog/blob/main/RELEASING.md) describes the release workflow.

## Translate with Guidedog

```sh
mkdir -p docs/manual/_editions
build/guidedog build -b gettext docs/manual docs/manual/locales/templates -W
build/guidedog intl update -p docs/manual/locales/templates \
    -l zh_CN -l ja -l ko -l hi -l es -l de docs/manual
build/guidedog intl stat -l zh_CN -l ja -l ko -l hi -l es -l de docs/manual
build/guidedog build -b html docs/manual docs/manual/_editions/de \
    -D language=de -D 'html_extra_path=[]' -W
```

Translate and review `msgstr` values in the PO files. Guidedog extracts POT files, merges catalogs, reports progress, and builds each edition. It does not invent translations. Commands, paths, code, API names, and reference targets stay unchanged. Only the manual and repository overview are translated; API and GDS remain English. See the [manual build instructions](howto/maintain-docs.rst) for assembling all editions and PDF books.

GitHub readers choose a README language using the links above. Automatic language selection belongs to the generated documentation website.

## Read and embed

- [Manual](index.rst): tutorials, topics, practical tasks, reference, and internals.
- [API reference](api/index): generated from Odin source and included in the manual's PDF appendix.
- {download}`Library guide <_static/repository/library-README.md>`: caller-owned workspaces, memory, and conversion examples.
- [Templates](templates.rst): customize HTML with Jinja and books with Typst.
- {download}`GDS <_static/repository/gds-README.md>`: numbered design records and implementation decisions.
- {download}`Beta review <_static/repository/beta-review-20261011.md>`: fixes, verification, support scope, and remaining release gates.

Guidedoc uses caller-provided storage and returns structured diagnostics. The host manages files, budgets, caching, publication, and native compilers. `--untrusted` restricts capabilities; it is not a process sandbox or a limit on all native resource use. The beta scope is trusted documentation projects on macOS and Linux.

## Credits and license

Created by **Vikrant Rathore**, with assistance from **Ronak Rathore** and **Kanak Rathore**. Contributions are welcome through issues and pull requests. Documentation credits use names or handles, not personal email addresses; Git identity settings are managed separately.

Thanks to Sphinx and Georg Brandl, Docutils and David Goodger, Typst, Tree-sitter and Max Brunsfeld, Graphviz, and Ginger Bill and the Odin community.

Guidedog is released under the {download}`GNU Affero General Public License v3.0 or later <_static/repository/LICENSE>` (AGPL-3.0-or-later). For other licensing terms, contact the authors. {download}`NOTICE <_static/repository/NOTICE>` says how to reach them and lists the third-party components, such as the bundled fonts, that keep their own licenses.

An additional permission allows Guidedog to be linked and distributed with Graphviz; see {download}`NOTICE <_static/repository/NOTICE>`.