Guidedog Manual
===============

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

Guidedog is a documentation generator that builds HTML websites and PDF books
from reStructuredText and Markdown sources. It operates as a self-contained
executable without requiring a Python environment or external LaTeX installation.
The conversion engine is called **Guidedoc**; PDF pages are typeset using Typst,
and the documentation website is generated directly.

A small project needs three things: a source document, a table of contents,
and ``conf.toml``. Start with :doc:`tutorial/first-project`.
For a particular task, use :doc:`howto/index`.
For an exact contract, use :doc:`reference/index`.

.. graphviz::
   :caption: One source project, two publications.
   :alt: RST and Markdown enter Guidedoc; HTML goes to a browser and Typst produces PDF.

   digraph publication {
     graph [rankdir=LR, bgcolor="transparent", pad="0.3"];
     node [shape=box, style="rounded,filled", fillcolor="#edf5f2",
           color="#216553", fontname="Helvetica", fontcolor="#16382f"];
     edge [color="#216553"];
     source [label="RST + Markdown\nconf.toml + assets"];
     engine [label="Guidedoc\nread · resolve · render"];
     html [label="HTML site\nlinks · navigation · search"];
     typst [label="Typst\noptimized typesetting"];
     pdf [label="PDF book\nchapters · figures · equations"];
     source -> engine; engine -> html; engine -> typst; typst -> pdf;
   }

.. toctree::
   :maxdepth: 2
   :caption: Learn

   tutorial/index
   topics/index

.. toctree::
   :maxdepth: 2
   :caption: Work

   howto/index
   reference/index

.. toctree::
   :maxdepth: 2
   :caption: Understand

   internals/index
   about
   repository

.. toctree::
   :maxdepth: 1
   :caption: API reference

   api/index