THE GITHTML FIELD GUIDE
Version documentation source and generated output deliberately
Decide explicitly whether generated HTML belongs in the repository, a separately managed artifact collection, or only a hosting output. Keep the authoring source authoritative and document the refresh process. A generated file’s presence in Git can support a reading workflow, but it does not automatically make the output current, reviewed, or publicly hosted.
Name the consumers of the output
List who needs the generated HTML and how they obtain it. A website host, an internal archive, and gitHtml may consume different artifacts. gitHtml needs actual .html files in the repository content it reads; Markdown authoring files alone do not satisfy that workflow.
Consider the volume and update frequency of generated files. A small stable handbook has different maintenance costs from a large API site that changes on every build. Choose a policy based on those concrete needs.
Define source authority and output ownership
Write down which files humans edit and which are generated. Name the responsible maintainer and the local build command. If generated HTML is retained, specify when it must be refreshed and how reviewers verify it corresponds to the source.
Keep output directories separate from source directories. Use build destinations that cannot accidentally erase authoring files. The policy should explain how to recognize stale output, not simply instruct contributors to remember to rebuild.
- List artifact consumers and their required formats.
- Document authoritative source paths, build command, and output owner.
- Record provenance and verify source-to-output agreement before distribution.
Make provenance easy to inspect
Attach a source revision, generator version, and target product version to important artifacts. Record the build configuration and dependencies needed to reproduce them. An export date is useful, but it does not replace the source identity.
During review, compare substantive source changes and inspect the final reading pages. Generated diffs can be noisy, so reviewers need both a clear source-level explanation and evidence that the output actually includes the intended correction.
Keep distribution and publication separate
Recording generated files in a repository is not the same as hosting a website. Decide separately whether those files should be public, private, or available only to a defined audience. Do not change repository visibility merely to simplify artifact access.
For a reading-oriented output, test the actual HTML and dependencies in the destination app. Keep historical artifacts clearly labeled and maintained guides easy to find. A useful policy gives the next maintainer a predictable route from a source edit to a reviewed, appropriately distributed reading copy.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.