THE GITHTML FIELD GUIDE
Make Pandoc HTML exports repeatable with a defaults file
Store recurring Pandoc conversion options in a reviewed defaults file, then run the export with that file explicitly selected. This reduces forgotten flags and makes the build recipe easier to inspect. Also record the Pandoc version and source revision: a defaults file describes settings, but it does not freeze every tool, template, or dependency.
Identify the settings that affect readers
List the input format, output format, standalone behavior, contents list, stylesheet, template, resource handling, and destination path. These choices influence the final reading experience. A one-off shell command becomes difficult to maintain when teammates quietly use different options.
Separate project-wide defaults from personal preferences. If the handbook is distributed to others, its important build settings should be visible in the project’s documented workflow rather than depending on a particular author’s home-directory configuration.
Create a small reviewed recipe
The example shows a YAML defaults file for an existing guide.md source and a dedicated HTML output. Save it under a clear name such as reading-export.yaml using your normal editor, then invoke Pandoc with --defaults=reading-export.yaml.
Keep the first recipe minimal. Add custom templates, filters, or embedding only when the document requires them and reviewers understand their role. Treat build configuration from an unfamiliar repository as code to review, especially when it invokes external filters.
from: markdown
to: html5
standalone: true
toc: true
input-files:
- guide.md
output-file: guide-reading.htmlRecord what the recipe cannot capture
Include the installed Pandoc version in your export notes, along with source revision and any custom template version. If images or other assets come from remote URLs, their content can change independently of the source text.
Prefer stable local assets for a reproducible reading packet. Document how resource paths are resolved and where the command is run. A recipe that works only from an undocumented directory is still fragile even when all its flags are saved.
Check output, not only repeatability
Run the export into a safe dedicated destination, inspect warnings, and compare the resulting document with the approved source. Review headings, links, metadata, and critical examples. Identical settings can consistently produce an undesirable result if the source assumptions are wrong.
For gitHtml distribution, confirm that the intended .html artifact is the file placed in the repository and tested in the reading environment. Keep the recipe and provenance available so the next maintainer can refresh the document without reconstructing your terminal history.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.