How to Version Reports and Technical Documentation with Markdown

If your files are named “final,” “final-2,” and “client-approved,” you are naming copies, not managing versions. A more reliable workflow keeps Markdown as the readable source, uses Git for the change history, marks deliverable states with tags or branches, and checks images, attachments, and generated files as part of the same release.

Separate the three meanings of “version”

Version confusion starts when change history, product compatibility, and delivered files receive one shared number. Keep these questions separate.

Git records how file contents change and lets you compare or restore earlier states. That applies to plain-text reports and Markdown files as well as source code. The Pro Git book explains the model.

Choose a version model for the document type

Do not begin by copying a whole directory for every small edit. First decide whether readers need a continuously updated page or an unchanged delivery artifact.

GitHub Docs uses YAML front matter and conditional content to describe version ranges while keeping shared prose in one source. That model fits documentation when most of the page is common and only some instructions vary.

Use a directory structure that can survive change

Keep Markdown, examples, images, and release notes in predictable locations. This structure is small enough for a team project and still leaves room for version tags:

docs-project/
├── docs/
│   ├── index.md
│   ├── api/
│   │   ├── overview.md
│   │   └── authentication.md
│   └── reports/
│       └── 2026-q3.md
├── assets/
│   ├── api-auth-flow.png
│   └── report-chart-2026-q3.png
├── CHANGELOG.md
└── README.md

Reference images relative to the Markdown file, such as ../assets/api-auth-flow.png. Avoid computer-specific absolute paths, and update every reference when an asset is renamed. For a Word conversion example, see Markdown Images Not Showing in Word? ZIP Packaging Guide.

Put the support boundary in front matter

Front matter is not a replacement for Git. It places the document’s applicability next to the content, where a reader and a build process can inspect it:

---
title: API Authentication
product: DocuCraftBox API
versions:
  api: [v2, v3]
status: maintained
last_reviewed: 2026-09-23
---

This page explains the shared authentication flow.

If a paragraph applies only to v3, do not duplicate the whole page by default. Extract shared content, use a reusable section, or use the conditional syntax supported by your build system. Create a separate version only when the difference changes the reader’s action or expected result.

Turn branches, commits, and tags into a release workflow

A small team can use the following workflow. The important part is the review boundary, not the number of Git commands:

1. Create a documentation branch from the current main line, such as docs/api-v3-auth.
2. Change the prose, examples, images, and front matter on that branch.
3. Use git diff to inspect commands, parameters, links, and version labels.
4. Ask a product owner to check facts and a reader-focused reviewer to check clarity and steps.
5. Build the docs or export the file and check pages, images, code samples, and attachments.
6. Create an immutable tag after approval, such as docs-2026-q3 or api-v3.2-docs.

git switch main
git pull
git switch -c docs/api-v3-auth
# edit Markdown, examples, and assets
git diff --check
git add docs/ assets/ CHANGELOG.md
git commit -m "docs: update API authentication for v3"
git push -u origin docs/api-v3-auth

GitHub’s documentation workflow follows the same basic pattern: inspect the branch, stage the intended files, commit, push, and merge through a pull request.

Reports and technical docs need different release rules

Reports: preserve the approved snapshot

A report’s numbers, conclusions, and charts usually belong to a specific cutoff. After approval, bind the source Markdown, images, data notes, and exported file to one tag or archive. If an error is found later, publish a new revision and explain whether the old version is still valid.

Technical docs: mark what is supported

Technical docs answer a more immediate question: “What should I do with the product in front of me?” Keep the current page easy to find, but give older supported APIs or product releases a clear entry point. A wording fix can usually update the current page; an incompatible behavior change needs a visible version split.

Write a changelog for readers, not a copy of the commit log

Commits are for maintainers. A CHANGELOG is for people deciding whether a release affects them. Each entry should say which version changed, what the reader will notice, and what action is required.

# Changelog

## 3.2.0 - 2026-09-23

### Changed
- API authentication examples now use the v3 header names.

### Fixed
- Corrected the relative path for the authentication flow image.

Common Changelog recommends reverse chronological releases, impact-based groups such as Added, Changed, Removed, and Fixed, and links to more detail.

Bring images, attachments, and exports into the boundary

Markdown is easy to diff, but binary attachments need a different check. Store charts, screenshots, CSV files, DOCX files, and PDFs with the Markdown version that references them. Check at least these points:

• File names are stable and do not rely on labels such as “final-new.”
• Relative paths work in local preview, the build environment, and the archive.
• Chart values match the reporting period of the document.
• The DOCX or PDF was generated from the tagged source, not an uncommitted local copy.

If you need to assemble report screenshots or charts into a shareable PDF, you can also review the Images to PDF tool. Treat that as an output step; it does not replace the Markdown source or Git history.

Run a ten-minute pre-merge check

1. Read the diff and remove draft notes, temporary paths, and local secrets.
2. Check heading levels and confirm that code samples remain copyable.
3. Open internal and external links; use anchor text that describes the destination.
4. Confirm that every meaningful image exists, fits the page, and has useful alt text.
5. Check that version labels, dates, API parameters, and examples describe the same release scope.
6. Build the site or export the document, then inspect the rendered result.
7. Make sure the CHANGELOG explains reader-visible impact.
8. Create the tag and record the commit used for generated files.

Troubleshooting table

FAQ

Does every Markdown file need a version number?

Not necessarily. Git commits and tags record the change and release boundaries. The page still needs to tell readers which product or API version it applies to. Keeping those questions separate is clearer than relying on one number in the file header.

Should a report use a branch or a tag?

Use a branch while the report is being written and reviewed. Use a tag for the approved snapshot. This lets the team discuss changes without changing the delivered state.

When should I copy a document into a new version?

Keep a separate entry point when the older version must remain available and the new instructions produce a different result. Spelling fixes, clearer links, and wording improvements usually belong in the current page.

Can Git replace documentation review?

No. Git shows what changed, but it cannot decide whether a parameter is correct, a screenshot is stale, or a reader can complete the task. Fact review, link checks, and rendered-output inspection still need explicit steps.

Next step

Choose one report or API guide that is still changing. Put its Markdown source, images, and exports in one predictable structure. Add the support metadata, make one review branch, inspect the diff, and tag the first approved delivery. Once that flow works, decide whether a version picker, automated build, or conditional content is worth adding.

Sources

• Pro Git: About Version Control.
• GitHub Docs: Using Git on GitHub Docs.
• GitHub Docs: Versioning documentation.
• Common Changelog.