Your first project¶
The aim is small: one page in a browser and the same page in a PDF. You need a build of Guidedog. For PDF output, Guidedog can use its embedded compiler or an installed Typst binary (0.15.1 or newer). See Build and install Guidedog.
On macOS, install the release with brew install insanai/guidedog/guidedog.
This adds the official tap and includes the PDF compiler.
Create the project¶
Run this from a directory where notes does not yet exist:
guidedog quickstart notes -q -p "Field Notes" -a "Your name" -v 1.0
Guidedog writes the configuration, the first RST document, and editable templates. It also creates folders for images, audio, and video. It refuses to overwrite an existing project.
notes/
conf.toml
index.rst
_templates/
layout.html
book.typ
_static/
guidedog.css
guidedog.js
assets/
images/
audio/
video/
_build/
The RST files hold your content. The templates hold your presentation.
The base templates (_templates/layout.html and _templates/book.typ)
are placed directly in your project by quickstart rather than being
stored in an external theme or package cache. You can inspect and
customize them at any time.
Write the first page¶
Replace notes/index.rst with:
Field Notes
===========
A useful explanation begins with a small example.
Measuring a square
------------------
If the side has length :math:`s`, its area is :math:`s^2`.
.. math::
A = s^2
.. note::
State the units before comparing measurements.
Build and inspect¶
guidedog build html notes -W
guidedog build pdf notes -W
Open notes/_build/html/index.html and the PDF in notes/_build/pdf.
-W makes warnings fail the build. Keep it in your documentation checks.
The HTML page contains the navigation and the text. The PDF adds book furniture.
Math is formatted for each target. Mathematics and proofs explains the setup.
Make a change¶
guidedog serve notes
Open the address printed by the command. Edit the source and save it. Refresh the browser page. Before serving HTML, Guidedog checks source modification times and rebuilds when they have advanced. It does not push a browser reload. Stop the server with Ctrl+C.
Build again without editing anything. Unchanged documents are reused. The build need not reread every page to prove that its output is current. Continue with Make a small book.