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.

Create and find Documents

Create a Document from the Documents workspace or from Add > Locus > Locus Document in a supported Content Browser folder. Locus creates a real external .md file, hides the extension in normal UI, and opens a dedicated editor tab.

The workspace browses physical folders and supports title/path search, status 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.

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.

The source editor provides commands for headings, emphasis, inline and fenced code, ordered and unordered lists, task lists, blockquotes, links, tables, horizontal rules, Asset References, and Pin References. Split Preview presents the current unsaved buffer beside the source after a short update delay; opening or updating Preview does not save the file.

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.

Source preservation

Readable presentation and Preview never regenerate the Markdown. Switching modes preserves the authored source exactly.

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.

Asset and Pin references use readable labels in presentation. A current-map Pin can be focused; a cross-map Pin can locate its owning level without automatically loading it. Missing references remain inert and diagnosable.

Rename, move, and delete

Rename and move stay within the Documents root. Provider-tracked or marked-for-add files cannot currently be renamed or moved through Locus because the provider boundary does not expose a safe move operation. Dirty or conflicted open Documents also block workspace rename, move, and delete.

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.

Source control

Documents are project-owned. They use the active provider for checkout, mark-for-add, and safe deletion, or remain locally editable in Local Mode. A new file is created locally before mark-for-add, so a provider failure does not discard the valid Markdown. Locus does not submit, sync, manage changelists, or change typemaps. See Source Control and Troubleshooting.