ATLANTIS ITS

MkDocs Setup & Usage

How-To Guide #007

Field Detail

Document ID HT-007

Version 1.0

Date March 11, 2026

Author Cooper (Copilot) --- formatted by Ozzy (Claude)

Reviewed By Shane Hardin

Applies To Atlantis OS / Documentation Layer

Difficulty Intermediate

Est. Time 15--20 minutes

Related Docs HT-001, HT-002, HT-003, TO-001

1. Overview

This guide explains how to install, configure, and use MkDocs as the official documentation and knowledge reference system for Atlantis.

MkDocs is not a file browser. It is a documentation publishing system that converts Markdown files into searchable, auditable web pages. Its primary value is institutional memory, searchability, and operational governance.

2. Why MkDocs Exists in Atlantis

MkDocs serves as the reference layer of Atlantis OS. It provides:

A single source of truth for procedures
Cross-document search across all KB content
Version history and auditability
Long-term operational memory

Markdown files become pages, not files.

💡 TIP: Think of MkDocs as the brain behind atlantisits.info --- every doc you write feeds it automatically once published.

3. Installing Pandoc (Markdown Conversion Tool)

Pandoc is used to convert Word documents (.docx) into Markdown (.md) files so they can be published in MkDocs.

3.1 Install via Chocolatey

Open PowerShell and run:

choco install pandoc

Verify the installation was successful:

pandoc --version

You should see a version number returned, e.g. pandoc 3.x.x.

⚠️ NOTE: If choco is not installed, install Chocolatey first: https://chocolatey.org/install --- run as Administrator.

4. Converting Word Docs to Markdown

Navigate in PowerShell to the folder containing your .docx file, then run:

pandoc HT-003-Vercel-502-Fix.docx -o HT-003-Vercel-502-Fix.md

Pandoc will silently generate a .md Markdown file in the same folder. No output message means success.

⚠️ NOTE: Do not rename .docx files manually --- always run the conversion command to generate the .md file. The .docx remains as an archival backup.

💡 TIP: To batch convert all .docx files in a folder, run: for %f in (*.docx) do pandoc \"%f\" -o \"%\~nf.md\"

5. MkDocs Folder Structure (Atlantis Standard)

All documentation lives under E:\Data\AtlantisITS\docs\Info with this structure:

docs/Info/

├── how-to/

│ ├── index.md ← Table of contents for this section

│ ├── HT-001-*.md

│ ├── HT-002-*.md

│ └── Originals/ ← .docx archival backups

├── tech-orders/

│ ├── index.md

│ ├── TO-001-*.md

│ └── Originals/

├── kb/

├── sop/

├── runbooks/

└── changelog/

Markdown files are canonical. Word files are archival backups only.

6. Making Docs Viewable in MkDocs

MkDocs only renders Markdown files that are explicitly linked. Each section folder must have an index.md file that acts as the table of contents for that section.

6.1 Example: how-to/index.md

Create or edit the file at docs/Info/how-to/index.md with this content:

# How-To Guides

## Available Guides

- [HT-001 Cloudflare Connector Rebuild](HT-001-Cloudflare-Connector-Rebuild.md)

- [HT-002 Docker Recovery Drive Migration](HT-002-Docker-Recovery-Drive-Migration.md)

- [HT-003 Vercel 502 Fix](HT-003-Vercel-502-Fix.md)

- [HT-004 MkDocs Setup & Usage](HT-004-MkDocs-Setup-Usage.md)

Each linked file becomes its own fully rendered web page on atlantisits.info.

⚠️ NOTE: If a .md file exists in the folder but is NOT listed in index.md, MkDocs will NOT render it. Always update index.md when adding a new doc.

The mkdocs.yml file at the root of docs/Info controls the full site navigation:

site_name: Atlantis ITS Knowledge Base

theme:

name: material

palette:

primary: cyan

accent: orange

nav:

- Home: index.md

- How-To Guides: how-to/index.md

- Knowledge Base: kb/index.md

- Tech Orders: tech-orders/index.md

- SOPs: sop/index.md

- Runbooks: runbooks/index.md

- Changelog: changelog/index.md

💡 TIP: Install the Material theme for a professional Atlantis-branded look: pip install mkdocs-material

7. Running MkDocs Locally

From the docs/Info directory in PowerShell:

cd E:\Data\AtlantisITS\docs\Info

mkdocs serve

MkDocs will start a local development server. Open your browser and go to:

http://127.0.0.1:8000

The site hot-reloads automatically --- any changes you save to .md files appear instantly in the browser without restarting.

💡 TIP: Run mkdocs serve in a separate PowerShell window so you can keep editing files while previewing the site.

8. Searching Documentation

MkDocs provides built-in full-text search across all rendered pages automatically --- no configuration needed.

The search engine:

Ignores folder structure --- searches content, not file paths
Surfaces relevant content across all sections simultaneously
Treats docs as knowledge, not files
Works offline on the local dev server

This is the primary long-term benefit of the system --- find any procedure in seconds across the entire Atlantis KB.

9. How MkDocs Fits into Atlantis OS

MkDocs is integrated as the Operations Guide layer within the Atlantis Control Center. It is the reference system the entire AI team and human operators consult before making infrastructure changes.

Use cases:

Use Case Description

Reference before changes Check the relevant TO or HT before touching any Atlantis system

Incident review Use runbooks during outages --- step-by-step recovery at 2am

Knowledge retention New team members onboard via the KB --- no tribal knowledge required

Audit and compliance Full version history and change log for every procedure

AI agent context Future RAG system will query atlantisits.info as its knowledge source

10. Key Takeaways

Principle What It Means

MkDocs is not a file viewer It publishes knowledge as web pages, not folder listings

Markdown files become web pages Every .md file = one rendered, searchable page

Index files control visibility If it\'s not in index.md, MkDocs won\'t render it

Search replaces browsing Full-text search across all docs --- no folder diving

Documentation becomes The KB is as critical as n8n, infrastructure Docker, and Cloudflare

.docx files are archival only Markdown is canonical --- Word docs live in Originals/ folders

11. Quick Reference --- Key Commands

Command Purpose

choco install pandoc Install Pandoc (one time)

pandoc --version Verify Pandoc is installed

pandoc HT-001.docx -o HT-001.md Convert a single Word doc to Markdown

pip install mkdocs-material Install MkDocs with Material theme (one time)

mkdocs serve Run local preview at http://127.0.0.1:8000

mkdocs build Build static site files for deployment

mkdocs gh-deploy Deploy directly to GitHub Pages (optional)

Content by Cooper (Copilot) --- formatted and published by Ozzy (Claude --- Atlantis AI Automations)

atlantisits.info | HT-007 | v1.0 | March 2026