Git is a version control system for code, but it works just as well for documentation. You get change history, branching, pull request reviews, and blame annotations out of the box. If your team already uses Git for code, putting docs in the same repo means one fewer tool to manage.

Why Git Works for Documentation

Markdown files are plain text. Git is built for plain text. That means you get every Git feature for free:

Version history. Every change is tracked. You can see who changed what, when, and why.
Branching. Write a big documentation overhaul on a branch without disrupting what’s live.
Pull request reviews. Teammates can review docs the same way they review code. Line-by-line comments, suggestions, approvals.
Blame and history. When a doc is wrong, git blame shows who last edited that line and links to the commit message explaining why.

Compare this to a wiki. Most wikis have some version history, but it’s usually a flat list of “Page edited by X at Y.” No branching. No review process. No way to batch related changes together.

A Practical Workflow

Here’s a workflow that works for teams of 2-50 developers:

Documentation lives in the repo alongside code, typically in a docs/ directory.
To update docs, create a branch and make your changes.
Open a pull request. Tag a reviewer.
Reviewer checks for accuracy, clarity, and completeness.
On merge to main, CI publishes the updated docs automatically.

main
 └── feature/update-api-docs (branch)
      ├── docs/api/endpoints.md (modified)
      └── docs/api/authentication.md (new)

This keeps documentation changes tied to the code changes that caused them. Updated a function signature? Update the docs in the same PR.

Branch Strategies for Docs

There are three common approaches. Each has tradeoffs.

Docs in the main branch (recommended). Keep a docs/ folder in your main repo. This is the simplest option. Docs stay close to the code they describe. When you update code, you update docs in the same PR. The downside: your repo has more files, and non-developers who contribute to docs need to understand Git.

Separate docs branch. Some teams keep docs on a dedicated branch like docs or gh-pages. This separates doc changes from code changes in the commit history. But it makes it harder to keep docs in sync with code, because they’re on different branches.

Separate docs repo. For large projects with dedicated technical writers, a separate repo can make sense. Writers get their own CI pipeline and permissions. The tradeoff: docs and code drift apart more easily. You need discipline to keep them in sync.

For most teams, docs in the main branch is the right call. It’s the simplest, and it naturally encourages keeping docs up to date.

Reviewing Documentation PRs

Code reviews and doc reviews need different checklists. When reviewing a documentation PR, check for:

Accuracy. Does the doc match what the code actually does? Run the examples if you can.
Audience. Is the doc written for the right reader? A getting-started guide reads differently than an API reference.
Completeness. Are there missing steps? Would a new developer be able to follow this?
Links. Do internal links point to the right places? Are external links still valid?

One useful practice: have someone unfamiliar with the feature review the doc. If they can follow it, the doc works.

Automating Publishing with CI/CD

The last step is getting docs online when they merge. Here’s a GitHub Actions workflow that publishes markdown files using MDtoLink whenever docs change on main:

name: Publish Docs
on:
  push:
    branches: [main]
    paths:
      - "docs/**/*.md"

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install MDtoLink
        run: npm install -g mdtolink

      - name: Publish changed docs
        env:
          MDTOLINK_API_KEY: ${{ secrets.MDTOLINK_API_KEY }}
        run: |
          for file in $(git diff --name-only HEAD~1 HEAD -- docs/); do
            if [[ "$file" == *.md ]]; then
              mdtolink publish "$file"
            fi
          done

This workflow only runs when markdown files in docs/ change. It installs the CLI, then publishes each changed file. Each file gets its own URL that you can share with your team or embed in your README.

For the full setup guide, see the GitHub Actions integration docs.

Handling Images and Assets

Markdown files reference images, and images don’t version as cleanly as text. A few approaches:

Relative paths. Store images next to the docs: docs/images/screenshot.png and reference them as ![alt](./images/screenshot.png). This keeps everything in the repo.
External hosting. Upload images to a CDN or image host and reference them by URL. This keeps the repo small but adds a dependency.
Git LFS. For repos with many large images, Git Large File Storage tracks binaries without bloating the repo. Run git lfs track "*.png" to set it up.

For most projects, relative paths are fine until your docs/images/ folder exceeds a few hundred megabytes.

Common Pitfalls

Docs rot. The biggest risk with docs-in-repo is that they go stale. The fix: require doc updates in the same PR as code changes. Add a checklist item to your PR template: “Documentation updated?”

Merge conflicts in docs. Multiple people editing the same doc creates conflicts. Keep docs modular. One file per topic. This reduces the chance of two people editing the same file.

Broken links. Internal links between docs break when you rename or move files. Consider a link-checking step in CI. Tools like markdown-link-check catch broken links before they ship.

Over-engineering. Not every project needs a docs-as-code pipeline. If you have three markdown files, publishing them with mdtolink publish is simpler than setting up a full CI pipeline. Match the tooling to the scale.

When to Use This Workflow

This Git-based workflow works best when your docs are closely tied to code, your team already uses Git, and you want review processes for documentation changes. For internal knowledge bases or non-technical docs, a wiki or Notion might be a better fit.

For more on documentation workflows, check out the documentation use case page.

Using Git for Documentation: A Markdown Workflow