Documentation Export Runbook¶
Status: Active packaging procedure. The destination repository owns MkDocs configuration and navigation.
Audience: Documentation maintainers exporting this repository's Markdown.
Scope¶
This runbook packages the repository's Markdown documentation for transfer to a separate GitLab MkDocs repository. No MkDocs configuration or destination import script is maintained here, so the destination repository remains the source of truth for navigation, theme, plugins, URL behavior, and deployment.
Required destination structure¶
The archive preserves paths relative to this repository root:
Extract that complete structure beneath the destination MkDocs docs_dir. For example, with the
default docs_dir: docs:
Preserving the common root is required for links such as
doc/lexical-and-game-architecture.md -> ../THIRD-PARTY-NOTICES.md to remain inside docs_dir.
Importing only the contents of doc/ would break links to the root-level files. Pages do not need
to appear in MkDocs navigation for relative links to resolve, although the destination may add them
to nav.
Documentation entrypoints¶
The exported pages have complementary entrypoint roles:
README.mdis the root repository and developer overview. It links todoc/index.mdfor audience-based documentation paths.doc/index.mdis the curated documentation landing page. It links back to../README.mdand is suitable as the MkDocs home page or first navigation item.
Keep both files at those relative paths so their links remain valid. The destination may point its
home navigation item at doc/index.md; it does not need to rename or duplicate that file as a
second root index.md. This runbook does not prescribe the destination mkdocs.yml.
Markdown-only ZIP¶
Run from the repository root:
$staging = Join-Path $env:TEMP 'minigames-docs-export'
$archive = Join-Path $PWD 'minigames-docs.zip'
Remove-Item $staging -Recurse -Force -ErrorAction SilentlyContinue
New-Item (Join-Path $staging 'doc') -ItemType Directory -Force | Out-Null
Get-ChildItem .\doc -Recurse -File -Filter '*.md' | ForEach-Object {
$relative = [IO.Path]::GetRelativePath((Resolve-Path .\doc), $_.FullName)
$destination = Join-Path (Join-Path $staging 'doc') $relative
New-Item (Split-Path $destination) -ItemType Directory -Force | Out-Null
Copy-Item $_.FullName $destination
}
Copy-Item .\README.md, .\THIRD-PARTY-NOTICES.md $staging
Get-ChildItem $staging -Recurse -File | Where-Object Extension -ne '.md' |
ForEach-Object { throw "Non-Markdown export file: $($_.FullName)" }
Remove-Item $archive -Force -ErrorAction SilentlyContinue
Compress-Archive -Path (Join-Path $staging '*') -DestinationPath $archive
Remove-Item $staging -Recurse -Force
The resulting minigames-docs.zip contains Markdown only. Inspect its paths before importing it.
Do not add heap dumps, production data, credentials, generated reports containing sensitive data,
or other runtime artifacts to this export.
Destination validation¶
After the GitLab MkDocs site exists, its import workflow should:
- Extract the archive beneath
docs_dirwithout flattening paths. - Configure destination-owned navigation and required Markdown extensions.
- Run the destination's strict MkDocs build to detect unresolved links and unsupported syntax.
- Review the generated site before publishing it.
The source ZIP procedure cannot guarantee rendered link behavior until it is tested against the
destination repository's actual mkdocs.yml and plugin set.