Keeping Blueprint Documentation in Git Alongside Your Project

The problem with documenting Blueprints in a separate wiki

If you have ever tried to keep Unreal Blueprint documentation under version control in Git, you already know the friction. The Blueprints live in your repository as binary .uasset files; the explanation of how they work lives somewhere else entirely. A Notion page, a Confluence space, an Obsidian vault, a shared drive. The moment those two things drift apart, the documentation is worse than useless, because now it is confidently wrong.

The deeper issue is that an external wiki has no idea your project uses branches. You refactor an ability system on a feature branch, you reword the wiki, and anyone still on main is now reading notes that describe code they do not have yet. There is no diff, no merge, no blame, no way to see who changed an explanation or when. The documentation simply is whatever the last person typed, detached from the commit history that gives the rest of your project its memory.

The fix is to stop treating documentation as a separate system and start treating it as source. If the notes are plain text and they live inside the repository next to the assets they describe, they branch when your project branches, merge when it merges, and travel in the same pull request as the change they document. That is exactly the model Markdown 4 Blueprints is built around.

Why plain .md beside your assets is version-control friendly

Markdown 4 Blueprints is an editor-only documentation tool that saves every note as a plain Markdown .md file inside your project, under Documentation/Blueprints/. That single design choice is what makes it source-control friendly. Markdown is text, and text is what Git was built to handle. Every edit produces a readable line-by-line diff, every note carries blame history, and a documentation change can be reviewed in the same pull request as the Blueprint change it explains.

Because the files live inside the project rather than in a remote service, there is nothing to keep in sync and nothing to forget. Clone the repository and you have the docs. Check out a branch and you have that branch's version of the docs. Roll back a commit and the notes roll back with it. The documentation can never describe a state of the project that your working copy is not actually in, because it is part of that working copy.

It is worth being precise about what the tool is. Markdown 4 Blueprints is an editor module, not a runtime widget. You author notes in a WYSIWYG editor tab inside the Unreal Editor, with live preview for headings, bold, italics, code blocks, tables and images, and it auto-saves the underlying .md roughly half a second after you stop typing. It does not render Markdown into your shipped game UI. Its job is to produce clean, diffable documentation files that sit alongside your assets, and it is fully offline with no external dependencies.

The Documentation/Blueprints folder layout, and what to commit

Notes are written to a folder structure that mirrors your content hierarchy. A per-asset note lands at Documentation/Blueprints/{AssetPath}.md, so the documentation for a given Blueprint sits at the same relative path as the Blueprint itself. Standalone notes that are not tied to any one asset live together under Documentation/Blueprints/Standalone/. The result is a documentation tree that maps onto your project tree, which makes it obvious in a diff which asset a changed note belongs to.

The tool also auto-detects the active asset, so when you open a Blueprint it loads the matching documentation, and it can switch content as you switch Blueprints. In practice that keeps the note and the asset coupled while you work, which is the same coupling you want preserved in source control.

For Git, the recommendation is simple: commit the whole Documentation/Blueprints/ tree. The .md files are small, text-based and human-readable, so they cost almost nothing in the repository and add real history. Treat a documentation edit like any other change and let it ride in the same commit or pull request as the Blueprint work it describes, so a reviewer sees the behaviour change and its explanation side by side.

Standalone notes, per-asset notes, and choosing a storage path

Not everything you need to document belongs to a single Blueprint. Architecture overviews, onboarding guides, design rationale and cross-system notes have no obvious owner asset, and that is what standalone notes are for. Create one with no asset focused and it is written under Documentation/Blueprints/Standalone/. Use per-asset notes for the how and why of an individual Blueprint, and standalone notes for the wider picture that ties several of them together. Both are plain .md, so both behave identically in Git.

The storage path itself is configurable. The plugin exposes a settings class, UBlueprintMarkdownSettings, as a UDeveloperSettings entry in Project Settings, where you can set the documentation storage path. If your team has a convention for where in-repo docs should live, point the tool at it once and every note follows. To keep things consistent, here is the practical sequence.

1. Open Project Settings and find the Blueprint Markdown section backed by UBlueprintMarkdownSettings.

2. Set the documentation storage path to wherever your repository keeps committed documentation, or leave it at the default Documentation/Blueprints/ if that already suits you.

3. Make sure that path is tracked by Git rather than ignored, so the .md files are committed with the rest of the project.

4. Author per-asset notes from an open Blueprint and standalone notes with no asset focused, letting auto-save write the files as you type.

5. Commit the documentation changes in the same pull request as the Blueprint changes they describe, so history stays joined up.

When you need a documentation bundle that lives outside the repository, for a client handoff or an archive, the one-click Export Notes option writes everything to an external project documentation folder while preserving the same structure, without disturbing the in-repo copies. Day to day, though, the win is the simplest one: your Blueprint docs are text, they sit next to your assets, and they are finally under the same version control as everything else you ship.

Where Blueprint documentation can live

Comparing an external wiki against in-repo Markdown notes for a version-controlled Unreal project.

FAQ