THE GITHTML FIELD GUIDE
Combine Markdown chapters into one HTML handbook
Use Pandoc with an explicit ordered list of Markdown inputs to create a single HTML handbook. Then check heading hierarchy, duplicate section identifiers, cross-references, and chapter-specific prerequisites. Combining files reduces cross-file navigation, but it does not automatically reconcile the editorial assumptions of documents that were originally written to stand alone.
Choose a coherent reading unit
Select chapters that support one audience and task, such as onboarding a new maintainer. Exclude unrelated reference material that would make the handbook harder to navigate. Decide whether each chapter still needs its original introduction or whether those introductions now repeat the same context.
Write the intended order explicitly. Alphabetical filenames may be convenient for storage but wrong for learning. Prerequisites should appear before procedures, and conceptual explanations should arrive before the first step that depends on them.
Build in the chosen order
The example lists overview, setup, and troubleshooting sources in the sequence Pandoc should read them. A table of contents can provide an entry route through the resulting standalone document. Use a new output filename so experimentation does not replace an approved handbook.
Pandoc normally combines multiple inputs before parsing. If your sources depend on independent parsing behavior, review its file-scope option and test that case deliberately. Do not assume every collection of separately rendered pages can be concatenated without changes.
pandoc overview.md setup.md troubleshooting.md --standalone --toc --output=handbook-reading.htmlRepair cross-chapter assumptions
Check links that previously pointed to another Markdown file. In a combined handbook, an appropriate destination may be a section anchor instead. Confirm the generated identifiers, especially where different chapters use the same heading text.
Review references such as above, next page, and see the sidebar. These phrases often lose meaning after merging. Give the handbook a consistent terminology, version statement, and explanation of which sections are required versus optional background.
Verify the whole artifact
Read the transition between chapters, inspect the contents list, and test links near the end of the handbook. Check images and code samples from every input, not just the first one. Resource paths may have been written relative to different source locations.
For portable use, package essential assets deliberately and prefer inline CSS. Put source paths and revision context in the document’s provenance note. A combined HTML handbook should feel intentionally edited, not like a pile of unrelated pages placed inside one wrapper.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.