Skip to content

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:

README.md
THIRD-PARTY-NOTICES.md
doc/
    adr/
    ...

Extract that complete structure beneath the destination MkDocs docs_dir. For example, with the default docs_dir: docs:

mkdocs.yml
docs/
    README.md
    THIRD-PARTY-NOTICES.md
    doc/
        adr/
        ...

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.md is the root repository and developer overview. It links to doc/index.md for audience-based documentation paths.
  • doc/index.md is the curated documentation landing page. It links back to ../README.md and 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:

  1. Extract the archive beneath docs_dir without flattening paths.
  2. Configure destination-owned navigation and required Markdown extensions.
  3. Run the destination's strict MkDocs build to detect unresolved links and unsupported syntax.
  4. 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.