# Combine Markdown chapters into one HTML handbook

Canonical: https://githtml.com/guides/combine-markdown-chapters-into-an-html-handbook
Published: 2026-09-26
Publisher: WaveTech LLC / gitHtml

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.

````sh
pandoc overview.md setup.md troubleshooting.md --standalone --toc --output=handbook-reading.html
````

## Repair 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

- [Pandoc: user manual](https://pandoc.org/MANUAL.html)
- [MDN: HTML anchor element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a)

## Related guides

- [Convert Markdown to standalone HTML with Pandoc](https://githtml.com/guides/convert-markdown-to-standalone-html-with-pandoc)
- [Embed resources in a Pandoc HTML export carefully](https://githtml.com/guides/embed-resources-in-pandoc-html-exports)
- [Make Pandoc HTML exports repeatable with a defaults file](https://githtml.com/guides/make-pandoc-exports-repeatable-with-defaults)
- [Build MkDocs HTML locally before sharing it](https://githtml.com/guides/build-mkdocs-html-locally)

Editorial approach: https://githtml.com/guides/about