Documents

Documents are project-owned Markdown files for longer-form project knowledge. The .md file is always authoritative and remains compatible with external text editors.

Ownership and storage

All Documents live beneath <Project>/ProjectDocuments/. There are no Shared or Private Document scopes. Content Browser folders under /Game/... map to corresponding paths beneath ProjectDocuments/Content/...; a Developers folder is still project context, not private ownership.

A Document is not a UAsset, package, redirector, runtime object, or cooked-data owner. Locus never wraps the Markdown in another authoritative format.

Locus Documents and Content Browser roots

The Documents tree has two presentation roots over that single physical repository:

Locus Documents contains ordinary project-owned Documents stored outside the reserved Content/ subtree. These Documents exist in Locus only and are not projected into Unreal’s Content Browser.
Content Browser contains only Documents whose authoritative relative path starts with Content/. Locus hides that internal storage prefix in the tree, so ProjectDocuments/Content/Blueprints/AI/Behavior.md appears as Content Browser > Blueprints > AI > Behavior and projects into /Game/Blueprints/AI.

The Content Browser root is sparse and Document-driven. It shows only folders that directly contain a projected Locus Document, plus ancestors required to reach those folders. It does not mirror unrelated /Game folders, and removing a derived presentation folder does not delete or modify the corresponding Unreal folder.

Projection follows the authoritative relative path, not the UI used to create the file. A mapped Document discovered at startup, created in Locus, created through Add > Locus > Locus Document, imported, or created through MCP has the same indexed identity and projection behavior.

Create and find Documents

Create beneath Locus Documents for a Locus-only Document. Create beneath Content Browser for a mapped Document that projects into the corresponding /Game context. Add > Locus > Locus Document in a supported Content Browser folder creates that same mapped identity. Locus creates a real external .md file, hides the extension in normal UI, and opens a dedicated editor tab. Markdown imports and MCP-created Documents follow the same local, Untracked creation policy.

Organize a new Document before adding it to source control:

Create → rename, move, and edit → Mark for Add when its path is final.

The workspace browses physical folders and supports title/path search; All, Needs Attention, Recovery, Conflict, and Read-only filters; refresh; open; rename; move; delete; checkout; mark for add; import; and export. Multiple Document tabs can be open at once; opening an already-open path focuses its existing tab.

The Documents toolbar remains one row. As space narrows, lower-priority actions move progressively into More Actions and return when room is available. Export and Refresh remain in that menu. Source-control actions are absent when no provider is configured.

To import, use the Content Browser Locus action and choose one valid UTF-8 .md file. Locus preserves its source bytes and line endings and uses a safe numbered name if the destination already exists.

Edit and save

New or empty Documents open in Edit Mode; populated Documents open in Read Mode. Press Ctrl+E for Edit Mode, Ctrl+R for Read Mode, and Ctrl+S to save. Documents use explicit save rather than Notes-style autosave.

In Edit, the compact formatting toolbar provides Heading, Bold, Italic, Inline Code, Unordered List, Ordered List, External Link, Asset Reference, and Pin Reference. Strikethrough, blockquote, task list, table, fenced code, and horizontal rule remain in the complete Format menu. The Format menu, formatting toolbar, and Split Preview control are absent in full Read Mode and return immediately in Edit Mode.

Split Preview presents the current unsaved buffer beside the source after a short debounce. Drag its divider to resize it or use Close in the Preview header. Preview defaults closed; its open state and split ratio are personal preferences restored across projects. Opening or updating Preview does not save the file or change recovery state.

Read Mode and Markdown support

Read Mode uses native Unreal UI. It supports the Markdown constructs needed by the editor toolbar, including headings, paragraphs, emphasis, strong text, lists, display-only task items, blockquotes, code, links, tables with alignment, horizontal rules, and strikethrough.

Locus does not claim browser-equivalent or complete Markdown rendering. Raw HTML remains inert source text, JavaScript never executes, unsafe URL schemes are not activated, and remote content is not fetched automatically. HTTP and HTTPS links open only after an explicit user action in the operating-system browser.

Locus Document Editor showing a project Markdown document in Read Mode with headings, list, and table — Documents keep Markdown as the source while Read Mode presents supported structure in native Editor UI.

Resolved Asset, Pin, Note, Document, and Actor references use readable labels in presentation and the same navigation behavior as Notes. Cross-map Pin and Actor navigation asks before using Unreal’s normal dirty-package save and level-open workflow. Actor references are authored by dropping exactly one eligible loaded World Outliner Actor into a Document in Edit Mode; they are not offered by Insert Reference or @. Missing references remain readable, inert, and diagnosable.

Rename, move, and delete

Rename and move stay within the Documents root. For an eligible Untracked Document, use Rename in the toolbar or context menu, press F2, use Move in the toolbar, or drag it onto a valid existing folder. The Locus Documents workspace is the authoritative place to rename or move; the Content Browser item is a projection and direct Content Browser rename is not supported.

After Mark for Add, Rename and Move are intentionally unavailable. They also remain unavailable for controlled Documents, because Locus cannot guarantee a provider-neutral depot move or transfer open state between paths. This safety boundary prevents a filesystem change from desynchronizing the Document and source control. Recovery, conflicts, or dirty open-editor state also block workspace rename and move.

Deletion is permanent, requires confirmation, and cannot be undone through Unreal. For tracked files, Locus validates and routes deletion through the active provider before local cleanup.

Export

Export a selected Document, a folder, all Documents, or an editor copy. Export preserves the current source—including an unsaved editor buffer when exporting a copy—and can preserve folder structure. The destination cannot be inside ProjectDocuments; collision choices include overwrite, skip, or a numbered copy. Export does not change the source Document, its tab, or source-control state.

Recovery and external editing

Locus stores Document recovery under <Project>/Saved/Locus/Recovery/Documents/. A successful save removes the corresponding snapshot. Clean external changes reload; an external change that conflicts with dirty local text blocks save until you choose a safe resolution.

Because .md is authoritative, external editors are supported. Refresh discovery after external file operations if the workspace does not update promptly. Editor tabs are not restored automatically after restarting Unreal Editor.

Opening another Locus Document prefers the active or most recently active Locus Document tab stack and appends the new tab beside that group. If no live Locus Document stack exists, Locus uses its normal dockable-tab fallback. Tabs remain freely dockable and may be separated by the user.

Selected Document preview

Selecting a Document shows a read-only Markdown preview in the workspace detail panel. It presents the saved, authoritative file; use the dedicated Document editor to read or edit content. During a normal short selection transition, the preview remains neutral until the selected content is ready. Only a wait longer than approximately one second shows a compact native loading explanation rather than stale content.

The Document filename and path provide its workspace identity. A Markdown heading is content, so renaming the file updates its displayed filename without rewriting a heading such as # My Title.

The Document Editor View menu has separate personal Source Font Size and Reading Font Size controls. Reading Font Size applies to full Read Mode and Split Preview, including headings, code, references, and table cells. Ctrl+mouse wheel over source or rendered content adjusts the applicable size; an unmodified wheel continues to scroll.

Source control

Documents are project-owned. A newly created Document remains Untracked until you explicitly choose Mark for Add, so it can be organized while its path is still changing. A local or untracked Document remains legitimately editable in Local Mode. If Mark for Add fails, the valid Markdown remains in place and can be retried. With no provider configured, Documents shows no source-control-specific status, guidance, tooltip, or actions.

An existing depot-controlled Document remains readable but cannot enter authoritative Edit Mode or Save until explicit checkout succeeds. Locus keeps those actions unavailable when the Document is clean and not checked out, checked out by another user or client, out of date, or disconnected from its provider. It offers no Make Writable fallback; Read Mode and Export Copy remain available where applicable.

After reconnecting source control, refresh restores the controlled state. The Document remains read-only until checkout succeeds. Locus does not submit, sync, manage changelists, or change typemaps. See Source Control, Project Impact & Dependencies, and Troubleshooting.