THE GITHTML FIELD GUIDE
Separate authoring sources from generated HTML
Treat the authoring files as the source of truth and the generated HTML as a reading artifact unless your project explicitly uses hand-written HTML. Find the generator configuration and build instructions before making corrections. gitHtml reads repository HTML; it does not turn a source directory into a generated documentation site.
Recognize the two layers
A repository may contain Markdown or reStructuredText, theme configuration, and an output directory full of HTML. Similar titles across those directories do not mean they are independent documents. One may be produced from the other during a local build.
Look for configuration files and maintained build instructions that explain the relationship. Do not infer the generator solely from a folder named docs; teams use that name for both source and output.
Locate the durable edit point
For a typo in a generated page, find the corresponding authoring section and make the proposed correction there through the normal review process. Editing only generated HTML can create a temporary improvement that disappears the next time output is rebuilt.
If the mapping is unclear, ask the maintainer for the source path and build command. Your issue report should include both the visible page URL and the affected text, allowing someone else to locate the source reliably.
- Identify the authoring file and generator configuration.
- Rebuild locally using the documented project command.
- Compare the corrected source with the final HTML output.
Choose what the reading repository needs
A local generator can produce a complete site, but the repository may intentionally exclude that output. A reader syncing .html files will need those files present in the selected repository content. This is a distribution decision, not an automatic consequence of running a generator.
For a small handbook, a focused standalone export may be easier to maintain than tracking every generated asset. For a large reference site, preserve the site as a collection and document its runtime requirements separately.
Check that the layers agree
After a local rebuild, compare the source correction with the final HTML. Confirm the title, body text, links, and version label. Generated output can lag behind source when a build was skipped or the wrong output directory was distributed.
Record a simple chain in your handoff: source path, generator and version, build command, output path, and reviewed revision. That chain makes later discrepancies diagnosable and helps readers distinguish an outdated artifact from an incorrect source document.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.