DocsHub Technical Design Document

Version: 2.0 Last Updated: 2026-02-11 Author: iSu Technologies Engineering Status: Production — Living Document

1. Executive Summary

DocsHub is iSu Technologies’ self-hosted, Git-backed static documentation platform serving as the central knowledge hub for the entire organisation. It currently serves 250+ markdown documents across 21 content categories covering products, prospects, operations, marketing, sales enablement, and internal processes.

This document is the single source of truth for DocsHub’s complete technical architecture, feature inventory, and functional specifications. It is designed to be platform-agnostic — if iSu Technologies migrates from MkDocs Material to Docusaurus, Sphinx, GitBook, or any alternative, this document provides everything needed to replicate the system without starting from scratch.

2. System Architecture Overview

2.1 Architecture Diagram

┌─────────────────────────────────────────────────────────┐
│                    USERS (Browser)                       │
│              https://docs.isutech.co.za                  │
└──────────────────────┬──────────────────────────────────┘
                       │ HTTPS (Let's Encrypt)
                       ▼
┌──────────────────────────────────────────────────────────┐
│                 NGINX (Reverse Proxy)                     │
│  ┌─────────────────────────────────────────────────────┐ │
│  │ • Static file serving from /var/www/docs/repo/site  │ │
│  │ • Gzip compression (level 6)                        │ │
│  │ • 1-year static asset caching                       │ │
│  │ • Security headers (XSS, clickjack, MIME)           │ │
│  │ • Hidden file blocking (dotfiles)                   │ │
│  │ • Optional: Basic auth per-section                  │ │
│  └─────────────────────────────────────────────────────┘ │
└──────────────────────┬──────────────────────────────────┘
                       │ Reads from filesystem
                       ▼
┌──────────────────────────────────────────────────────────┐
│              STATIC SITE (Built HTML/CSS/JS)              │
│                    /var/www/docs/repo/site/               │
│              ~44 MB generated output                      │
└──────────────────────┬──────────────────────────────────┘
                       │ Built by
                       ▼
┌──────────────────────────────────────────────────────────┐
│                  BUILD PIPELINE (Cron)                     │
│                                                           │
│  ┌─ Every 10 minutes ──────────────────────────────────┐ │
│  │ 1. git pull origin main                             │ │
│  │ 2. python3 update-frontpage.py                      │ │
│  │    ├─ Count docs → hero stats                       │ │
│  │    └─ Parse git log → What's New cards              │ │
│  │ 3. mkdocs build --clean                             │ │
│  │ 4. chown -R docs:docs site/ && chmod 755            │ │
│  └─────────────────────────────────────────────────────┘ │
└──────────────────────┬──────────────────────────────────┘
                       │ Pulls from
                       ▼
┌──────────────────────────────────────────────────────────┐
│               GIT REPOSITORY (GitHub)                     │
│       github.com/gedeza/isutech-knowledge-hub             │
│  Branch: main │ Visibility: Private                      │
└──────────────────────────────────────────────────────────┘

2.2 Deployment Topology

Component	Location	Details
Server	Hetzner VPS (46.224.40.5)	Ubuntu/Debian, 5.15.0 kernel
Web Server	Nginx	Serves static HTML from `site/`
SSL	Let’s Encrypt via Certbot	Auto-renewal enabled
Repository	`/var/www/docs/repo/`	Git clone of main branch
Python venv	`/var/www/docs/venv/`	Isolated MkDocs environment
Cron script	`/var/www/docs/scripts/update-docs.sh`	Symlink to `deployment/update-docs.sh`
Build output	`/var/www/docs/repo/site/`	Nginx document root
Logs	`/var/log/docs-update.log`	Build pipeline logs
Nginx logs	`/var/log/nginx/docs-{access,error}.log`	HTTP request logs

3. Technology Stack

3.1 Current Stack (MkDocs Material)

Layer	Technology	Version	Purpose
Static Site Generator	MkDocs	1.6.1	Markdown → HTML build engine
Theme	Material for MkDocs	9.6.23	UI framework, components, search
Search	Lunr.js (built-in)	—	Client-side full-text search
Git dates	mkdocs-git-revision-date-localized-plugin	1.3.0	”Last updated” timestamps from git
Minification	mkdocs-minify-plugin	0.8.0	HTML/CSS/JS minification
Git	GitPython	3.1.45	Python git operations (transitive dep)
Language	Python	3.x (system)	Build toolchain runtime
Web Server	Nginx	System	Static file serving + TLS termination
SSL	Let’s Encrypt / Certbot	—	HTTPS certificate management
Version Control	Git / GitHub	—	Source control, collaboration
CI/CD	Cron (server-side)	—	10-minute auto-pull + rebuild
Custom Automation	update-frontpage.py	—	Dynamic hero stats & changelog
DNS	External DNS provider	—	docs.isutech.co.za → 46.224.40.5

3.2 Python Dependencies (requirements.txt)

mkdocs-material==9.6.23
mkdocs-git-revision-date-localized-plugin==1.3.0
mkdocs-minify-plugin==0.8.0

Transitive dependencies installed automatically: mkdocs, mkdocs-material-extensions, gitpython, gitdb, Jinja2, Markdown, PyYAML, Pygments, pymdown-extensions, etc.

3.3 Stack Decision Rationale

Decision	Why
MkDocs over Docusaurus	Python ecosystem matches team skills; simpler config than React-based alternatives
Material theme	Best-in-class documentation theme; built-in search, dark mode, responsive design, 8000+ icons
Self-hosted over SaaS	Data sovereignty for sensitive business documents; no per-seat pricing
Cron over webhooks	Simpler infrastructure; 10-min latency acceptable for internal docs
Static site over CMS	No database, no auth server, no session management — just files

4. Feature & Function Specifications

4.1 Feature Inventory

Every feature below is implemented and production-active. Each includes the implementation mechanism so it can be replicated on any platform.

F-001: Full-Text Client-Side Search

Attribute	Value
Status	Active
Mechanism	Lunr.js index built at compile time, served as JSON
Configuration	`separator: '[\s\-\.]+'` for hyphenated/dotted terms
Features	Search suggestions, result highlighting, shareable search URLs
UX	Accessible via `/` keyboard shortcut or search bar

Platform Migration Notes:

Docusaurus: Use @docusaurus/plugin-content-docs with Algolia DocSearch or local search plugin
Starlight: Pagefind built-in — zero configuration, runs at build time, ~5KB client bundle
Sphinx: Use sphinx.ext.autosummary + sphinx_search or Algolia
Any: Client-side search requires a JSON index; server-side search requires Elasticsearch/Meilisearch

F-002: Light/Dark Mode Toggle

Attribute	Value
Status	Active
Mechanism	Material theme `palette` config with toggle icons
Light scheme	`default` with custom gold primary
Dark scheme	`slate` with custom gold primary
Persistence	Browser localStorage (handled by Material JS)

Implementation:

palette:
  - scheme: default
    toggle:
      icon: material/brightness-7
      name: Switch to dark mode
  - scheme: slate
    toggle:
      icon: material/brightness-4
      name: Switch to light mode

Platform Migration Notes:

Docusaurus: Built-in colorMode in docusaurus.config.js
Starlight: Built-in with OS auto-detection + manual toggle; dark/light CSS vars in --sl-color-*
Sphinx: Use furo or sphinx-book-theme with dark mode support
Any: Requires CSS custom properties switching + JS toggle + localStorage

Attribute	Value
Status	Active
Mechanism	Material `navigation.instant` with XHR page fetching
Prefetch	Pages prefetched on hover (`navigation.instant.prefetch`)
Progress	Loading bar shown during navigation (`navigation.instant.progress`)
URL tracking	URL updates as user scrolls (`navigation.tracking`)

Platform Migration Notes:

Docusaurus: Built-in SPA (React Router)
Starlight: Built-in via Astro’s View Transitions API (optional, zero-JS by default); prefetch on hover
Sphinx: Not native; requires custom JS or sphinx-immaterial
Any: Implement with fetch() + history.pushState() + DOM diffing

Attribute	Value
Status	Active
Top-level tabs	13 sections (Home, About, Marketing, BD, Projects, Case Studies, Prospects, Sales, Operations, Knowledge Base, Products, Templates)
Sticky tabs	Tabs remain visible on scroll
Section indexes	Directory README.md files serve as section landing pages
Expandable sections	All sections expanded by default
Breadcrumbs	Path navigation shown (`navigation.path`)
Back to top	Floating button on long pages

Complete Navigation Tree (13 top-level sections, 100+ pages):

Home
├── Getting Started
├── User Guide
├── Admin Guide
├── Document Standards
└── Phase 2 Deployment

About
├── Company Overview
├── Metrics & Impact
└── Technology Stack

Marketing
├── Overview, Quick Start, Cheat Sheet, Tracking, Examples
└── Email Templates (Event, Follow-up, Prospecting, Partnerships)

Business Development → Overview

Projects → Overview

Case Studies
├── Template
├── MGSLG, ThriveSend, Moses Kotane

Prospects & Opportunities
├── Sepfluor (12 docs)
├── SPAR (6 docs)
├── SACE (6 docs)
├── HPCSA (6 docs)
├── NSTF (13 docs)
└── SANSA (14 docs, grouped by phase)

Sales Enablement
├── ThriveSend B2B2G (One-Pager, ROI, Demo Script)
└── AssessFlow (One-Pager, ROI)

Operations
├── Server Management (Hetzner, Monitoring, Dev Workflow)
├── PLG Stack (8 docs: Install, Config, Alerting, Operations, Troubleshooting, Queries, Runbooks, Onboarding)
├── Security (5 docs: Overview, fail2ban, SSH, Kernel, Firewall)
├── DocuHub CLI Reference
├── HR (Onboarding, Remote Work)
└── Development (Code Review Standards)

Knowledge Base → Overview

Products
├── Product Comparison Matrix
├── ThriveSend B2B2G (8 docs + 3 use cases)
├── ThriveSend Technical (Getting Started, User Guide, Developer Guide, Architecture, API, Compliance, Deployment)
├── AssessFlow (8 docs + 3 use cases)
├── DocsHub Market Research (5 docs)
├── DocsHub Sales (6 docs)
├── AutoSlip Sales (6 docs)
└── Strategic Plan

Templates
├── BD Templates (Proposal, Business Case, Opportunity Assessment)
└── Project Templates (Project Charter)

Platform Migration Notes:

Docusaurus: sidebars.js with category and doc items
Starlight: sidebar array in astro.config.mjs; supports autogenerate: { directory: 'path' } for auto-nav from folders
Sphinx: toctree directives in index.rst files
Any: Requires sidebar generation from directory structure or explicit config

F-005: Dynamic Front Page (Auto-Updated)

Attribute	Value
Status	Active
Script	`deployment/update-frontpage.py`
Trigger	Runs before every `mkdocs build` via cron pipeline
Marker system	HTML comments: `<!-- AUTO:SECTION -->...<!-- /AUTO:SECTION -->`

Sub-features:

Component	Source	Logic
Document count	Filesystem `docs/*/.md`	Count excluding index.md, README.md, assets/; round down to nearest 5 with ”+“
Category count	Top-level dirs under `docs/`	Exclude 00-INDEX, assets, stylesheets, archive
Product count	Subdirs under `docs/products/`	Direct count
What’s New cards	`git log --since=90days`	Filter significant commits (feat/fix/docs/redesign/style prefixes), skip noise (Merge/WIP/Sync), group by (date, primary_subdir), render top 3 as Material grid cards
Manual overrides	`deployment/changelog-overrides.json`	Optional JSON array; overrides prepended before auto cards, total capped at 3

Icon Mapping (28 directory → icon mappings):

Directory Pattern	Icon
`prospects/sansa`	`:material-satellite-variant:`
`operations/infrastructure/security`	`:material-shield-lock:`
`operations/infrastructure/plg-stack`	`:material-chart-areaspline:`
`products/thrive-send-b2b2g`	`:material-send:`
`products/thrivesend-technical`	`:material-send:`
`products/autoslip`	`:material-receipt:`
`products/docshub`	`:material-book-open-variant:`
`products/assess-flow`	`:material-clipboard-check:`
`marketing`	`:material-email-outline:`
`case-studies`	`:material-trophy:`
`operations`	`:material-cog:`
(fallback by prefix)	feat→`:material-star-four-points:`, fix→`:material-wrench:`, docs→`:material-file-document-edit:`

Platform Migration Notes:

The marker-comment splice pattern is platform-agnostic (works with any markdown/HTML file)
The Python script is independent of MkDocs — it manipulates markdown text, not MkDocs APIs
For Docusaurus: modify script to target src/pages/index.tsx or docs/intro.md
For Starlight: modify script to target src/content/docs/index.md or src/content/docs/index.mdx
For Sphinx: modify script to target docs/index.rst (adapt markdown → RST rendering)

F-006: Git-Based “Last Updated” Dates

Attribute	Value
Status	Active
Plugin	`git-revision-date-localized`
Shows	Last modified date + creation date per page
Format	Date only (no time)
Source	Git commit history (not filesystem mtime)

Platform Migration Notes:

Docusaurus: showLastUpdateTime: true in plugin options (uses git natively)
Starlight: lastUpdated: true in config (built-in, uses git — zero configuration)
Sphinx: sphinx-last-updated-by-git extension
Any: Run git log -1 --format=%ai -- <file> per document

F-007: Mermaid Diagrams

Attribute	Value
Status	Active
Mechanism	`pymdownx.superfences` with Mermaid custom fence
Syntax	```mermaid ... ``` code blocks
Rendering	Client-side via Mermaid.js (bundled by Material)

Configuration:

- pymdownx.superfences:
    custom_fences:
      - name: mermaid
        class: mermaid
        format: !!python/name:pymdownx.superfences.fence_code_format

Platform Migration Notes:

Docusaurus: @docusaurus/theme-mermaid plugin
Starlight: @astrojs/starlight-mermaid integration or remark-mermaidjs remark plugin
Sphinx: sphinxcontrib-mermaid extension
Any: Include mermaid.js CDN + render <div class="mermaid"> blocks

F-008: Code Syntax Highlighting

Attribute	Value
Status	Active
Engine	Pygments (server-side at build time)
Features	Line numbers, line anchors, language auto-detection, copy button
Inline	Inline code highlighting via `pymdownx.inlinehilite`

Platform Migration Notes:

Docusaurus: Prism.js (client-side) — built-in
Starlight: Shiki (build-time, zero client JS) — built-in with line numbers, copy button, diff highlighting
Sphinx: Pygments (built-in)
Any: Prism.js or highlight.js for client-side; Pygments or Shiki for build-time

F-009: Admonitions (Callout Boxes)

Attribute	Value
Status	Active
Syntax	`!!! note "Title"` / `??? note "Title"` (collapsible)
Types	note, abstract, info, tip, success, question, warning, failure, danger, bug, example, quote
Custom styling	Gold left border via CSS

Platform Migration Notes:

Docusaurus: :::note / :::tip etc. (built-in)
Starlight: :::note / :::tip / :::caution / :::danger (built-in Asides) — same syntax as Docusaurus
Sphinx: .. note:: / .. warning:: directives (built-in)
Any: Requires markdown-it plugin or custom HTML <div class="admonition"> blocks

F-010: Content Tabs

Attribute	Value
Status	Active
Syntax	`=== "Tab 1"` / `=== "Tab 2"` blocks
Cross-linking	Tabs sync across pages (`content.tabs.link`)
Style	Alternate (Material-specific)

Platform Migration Notes:

Docusaurus: <Tabs> / <TabItem> JSX components
Starlight: <Tabs> / <TabItem> (built-in components, same API as Docusaurus)
Sphinx: sphinx-tabs extension
Any: Custom JS tabs component

F-011: Material Grid Cards

Attribute	Value
Status	Active
Syntax	`<div class="grid cards" markdown>` with `-` list items
Layout	3-column default; 4-column on 1400px+; 2-column tablet; 1-column mobile
Styling	Colored left borders (blue, purple, green, orange cycling), glassmorphism icons, hover transforms
Icons	8000+ Material Design icons via `:material-icon-name:` syntax

Custom CSS Components for Cards:

CSS Class	Purpose
`.grid.cards`	Card container grid
`.grid.cards > ul > li:nth-child(N)`	Per-card accent colors (4-color rotation)
`.lg.middle`	Glassmorphism icon container (backdrop-filter blur, border, shadow)
`.grid.cards svg`	Icon sizing (2rem) and color matching

Platform Migration Notes:

Docusaurus: Custom React component or @docusaurus/plugin-content-docs with MDX cards
Starlight: <Card> + <CardGrid> + <LinkCard> built-in components — zero extra packages needed
Sphinx: sphinx-design extension for card directives
Any: CSS grid + custom HTML/markdown components

F-012: Task Lists

Attribute	Value
Status	Active
Syntax	`- [x] Done` / `- [ ] Todo`
Style	Custom checkboxes (Material-themed)

F-013: Keyboard Shortcuts Display

Attribute	Value
Status	Active
Syntax	`++ctrl+alt+del++` renders as styled keyboard keys
Extension	`pymdownx.keys`

F-014: Math/LaTeX Rendering

Attribute	Value
Status	Active (configured)
Syntax	$...$ inline, `$$...$$` block
Engine	MathJax (generic mode via `pymdownx.arithmatex`)

F-015: Abbreviations & Glossary

Attribute	Value
Status	Active
Syntax	`*[abbr]: Full text` at end of document
Behavior	Hover tooltip shows full text on abbreviation occurrences

F-016: Footnotes

Attribute	Value
Status	Active
Syntax	`[^1]` reference, `[^1]: Text` definition
Behavior	Click to jump; back-reference link

F-017: Edit/View Source Links

Attribute	Value
Status	Active
Edit URI	`https://github.com/gedeza/isutech-knowledge-hub/edit/main/docs/`
Buttons	Pencil icon (edit), Eye icon (view source) on every page

Attribute	Value
Status	Active
Links	GitHub repository, iSu Technologies website
Position	Site footer

F-019: Versioning Support (Configured)

Attribute	Value
Status	Configured, not actively used
Provider	`mike` (MkDocs versioning tool)
Purpose	When ready, supports multiple doc versions (v1, v2, latest)

F-020: HTML Minification

Attribute	Value
Status	Active
Plugin	`mkdocs-minify-plugin`
Scope	HTML, JS, CSS minified; HTML comments removed

F-021: Print Stylesheet

Attribute	Value
Status	Active
Mechanism	`@media print` CSS rules
Behavior	Hides header, tabs, sidebar, footer; white background

4.2 Custom UI Components (CSS)

These are custom-built visual components defined in extra.css that content authors use via HTML classes in markdown documents:

Component	CSS Class(es)	Usage
Hero Section	`.hero-section`, `.hero-title`, `.hero-subtitle`, `.hero-buttons`	Landing page hero banner with grid overlay
Hero Stats	`.hero-stats`, `.hero-stat`, `.hero-stat-value`, `.hero-stat-label`	Stat counters in hero (auto-updated)
Service Cards	`.service-card`	Bordered cards with gold hover glow
Metric Cards	`.metric-card`, `.metric-large`, `.metric-label`, `.metric-badge`	KPI display cards with gold gradient badges
Status Badges	`.badge`, `.badge-success`, `.badge-warning`, `.badge-info`, `.badge-gold`	Colored pill badges
Stat Boxes	`.stat-box`	Gold-bordered stat callouts
Timeline	`.timeline`, `.timeline-item`	Vertical gold timeline with circular markers
Feature Grid	`.feature-grid`, `.feature-item`, `.feature-icon`	Auto-fit responsive feature showcase
Screenshots	`.screenshot`, `.screenshot-caption`	Bordered image containers with captions
Diagrams	`.diagram`	Bordered containers for ASCII/code diagrams
Highlight Boxes	`.highlight-box`	Gold-bordered emphasis containers
Progress Bars	`.progress-bar`, `.progress-fill`	Gold gradient animated bars
ROI Calculator	`.roi-calculator`, `.roi-result`, `.big-number`	Gold gradient result displays
Tech Stack Pills	`.tech-stack`, `.tech-item`	Rounded pill layout for technology lists
Comparison Tables	`.comparison-table`	Gold gradient header tables
Testimonials	`.testimonial`, `.testimonial-author`, `.testimonial-role`	Gold-bordered italic quote blocks
CTA Boxes	`.cta-box`	Gold gradient call-to-action sections
Quick Access Tables	`.quick-links`	Side-by-side reference tables
Section Headers	`.section-header`	Flex headers with gold underline

5. Brand Design System

5.1 Color Palette

Token	Hex	Usage
`--isu-gold`	`#B8860B`	Primary brand color, links, accents
`--isu-gold-light`	`#DAA520`	Hover states, gradients
`--isu-gold-dark`	`#996515`	Active states, gradient endpoints
`--isu-black`	`#1a1a1a`	Text, headers
`--isu-gray`	`#6b7280`	Subtitles, secondary text
`--isu-gray-light`	`#f3f4f6`	Backgrounds, code blocks

Card Accent Colors (4-color rotation):

Position	Color	Hex
Card 1	Blue	`#3b82f6`
Card 2	Purple	`#8b5cf6`
Card 3	Green	`#10b981`
Card 4	Orange	`#f59e0b`

5.2 Typography

Element	Font	Weight	Size
Body text	Roboto	400	1rem (16px)
Code	Roboto Mono	400	—
Hero title	Roboto	700	2.25rem desktop, 1.5rem mobile
H1	Roboto	—	1.75rem mobile
H2	Roboto	—	1.5rem mobile
Buttons	Roboto	500	—

5.3 Spacing & Layout

Property	Value
Content max-width	1800px
Grid max-width	95% of viewport
Card border-radius	12px
Button border-radius	50px (pill)
Grid background	50px gold grid overlay (3% opacity)
Card gap	1.5rem
Section spacing	`<hr>` with 1.5rem margin

5.4 Responsive Breakpoints

Breakpoint	Behavior
1400px+	4-column card grid
1000–1399px	3-column card grid
769–900px	2-column card grid, 2-column features
768px (tablet)	1-column cards, stacked hero buttons, scrollable tables
480px (phone)	Tighter spacing, smaller icons (3rem), smaller fonts
Landscape phones	1.5rem content padding
Touch devices	Disabled hover transforms, 44px min touch targets

5.5 Visual Effects

Effect	Implementation
Glassmorphism icons	`backdrop-filter: blur(10px)`, semi-transparent white background, subtle border
Card hover	`translateY(-4px)`, colored box-shadow (matching accent), background gradient intensification
Icon hover	`scale(1.08) rotate(-3deg)`, intensified colored shadow
Button hover	`translateY(-2px)`, gold box-shadow
Gold grid overlay	CSS `linear-gradient` background-image on `body` and `.hero-section::before`

5.6 Assets

Asset	Path	Usage
iSu Logo	`docs/assets/images/isutech-logo.png`	Header logo + favicon

6. Content Architecture

6.1 Content Statistics

Metric	Value
Total markdown files	251
Active content files	~240 (excluding index/README)
Content categories	21 top-level directories
Products documented	6 (ThriveSend B2B2G, ThriveSend Technical, AssessFlow, DocsHub, AutoSlip, DocsHub Market Research)
Prospect tracks	7 (Sepfluor, SPAR, SACE, HPCSA, NSTF, NSF Skills Dev, SANSA)
Total content size	~9.5 MB markdown
Built site size	~44 MB HTML/CSS/JS/assets

6.2 Content Taxonomy

docs/
├── 00-INDEX/           # Standards, guides, getting started (7 files)
├── about/              # Company overview, metrics, tech stack (3 files)
├── archive/            # Deprecated content
├── assets/images/      # Logo and static images
├── business-analysis/  # Opportunity assessments, stakeholder mapping
├── business-development/  # BD overview
├── case-studies/       # MGSLG, ThriveSend, Moses Kotane (4 files)
├── compliance-governance/ # Compliance docs
├── demo-presentation/  # Demo materials
├── deployment/         # Deployment docs (meta)
├── development/        # Development journal
├── document-templates/ # BD templates, project templates (4 files)
├── infrastructure/     # Hetzner server management
├── knowledge-base/     # Organisational knowledge
├── marketing/          # Email templates, campaigns (10+ files)
├── operations/         # Server, HR, dev workflow, security, PLG stack (20+ files)
├── products/           # 6 product lines (50+ files)
├── project-planning/   # Cost breakdowns, financial analysis
├── projects/           # Active projects overview
├── prospects/          # 7 prospect tracks (60+ files)
├── prototype/          # Data models, MVP features, requirements
├── sales-enablement/   # ThriveSend + AssessFlow sales materials (5 files)
├── stakeholder-materials/ # Demos, presentations, ROI analysis
├── stylesheets/        # extra.css (custom branding)
└── technical-architecture/ # Architecture docs

6.3 Document Standards

Defined in 00-INDEX/DOCUMENT_STANDARDS.md:

Standard	Rule
File naming	`lowercase-with-hyphens.md`
Dated docs	`YYYY-MM-DD-name.md`
Client docs	`client-name-document-type-vX.md`
Templates	`document-type-template.md`
Directory index	`README.md` in each directory
Metadata	Frontmatter with title, date, author, status
Lifecycle	Draft → Review → Published → Archived
Headings	H1 for title, H2 for sections, H3 for subsections

6.4 Prospect Document Pattern

Each prospect follows a standardised document set (varies by maturity):

Document	Purpose
`executive-summary-one-pager.md`	1-page overview for decision-makers
`pricing-investment-options.md`	Tiered pricing proposals
`demo-script.md`	Structured demo walkthrough
`objection-handling-guide.md`	Common objections + responses
`competitive-positioning.md`	Competitive analysis
`implementation-roadmap.md`	Phased delivery plan
`technical-overview.md`	Architecture & integration details
`first-outreach-message.md`	Initial email templates
`discovery-meeting-preparation.md`	Meeting prep guide
`case-studies-proof-points.md`	Relevant proof points

7. Deployment Pipeline

7.1 Build Pipeline Flow

┌─────────┐    ┌──────────┐    ┌──────────────────┐    ┌─────────────┐    ┌──────────┐
│  Cron    │───►│ git pull  │───►│ update-frontpage │───►│ mkdocs build│───►│  chmod   │
│ (10 min) │    │ origin    │    │     .py          │    │  --clean    │    │ docs:docs│
└─────────┘    │ main      │    │                  │    │             │    │  755     │
               └──────────┘    └──────────────────┘    └─────────────┘    └──────────┘

7.2 update-docs.sh (Build Script)

Location: deployment/update-docs.sh Cron: */10 * * * * /var/www/docs/scripts/update-docs.sh

#!/bin/bash
LOG_FILE="/var/log/docs-update.log"
REPO_DIR="/var/www/docs/repo"
VENV_DIR="/var/www/docs/venv"

# 1. Navigate to repo
cd $REPO_DIR

# 2. Pull latest
git pull origin main

# 3. Activate venv
source $VENV_DIR/bin/activate

# 4. Auto-update front page (hero stats + What's New)
python3 $REPO_DIR/deployment/update-frontpage.py

# 5. Build
mkdocs build --clean

# 6. Set permissions
chown -R docs:docs $REPO_DIR/site
chmod -R 755 $REPO_DIR/site

7.3 update-frontpage.py (Dynamic Content Generator)

Location: deployment/update-frontpage.py CLI flags: --dry-run (stdout only), --verbose (debug logging)

Function	Purpose
`count_docs()`	Counts `.md` files under `docs/` excluding index, README, assets
`count_categories()`	Counts content directories (excludes 00-INDEX, assets, stylesheets, archive)
`count_products()`	Counts subdirectories under `docs/products/`
`round_down_to_5()`	Displays doc count as `250+` style
`get_git_log()`	Runs `git log --since=90days --name-only -- docs/`
`parse_git_log()`	Structures raw log into `{hash, date, message, files}`
`get_primary_subdir()`	Maps file list to primary content directory
`group_commits()`	Groups by (date, subdir), filters noise, selects significant
`render_card()`	Generates Material grid card markdown
`splice_content()`	Replaces content between `<!-- AUTO:SECTION -->` markers
`load_overrides()`	Reads optional `changelog-overrides.json`

Safety guarantees:

Never crashes the build (all errors caught, exit 0)
Idempotent (skips unchanged files)
Falls back gracefully if git is unavailable

7.4 Changelog Override Format

Optional file: deployment/changelog-overrides.json

[
  {
    "icon": ":material-rocket:",
    "title": "Major Product Launch",
    "month_year": "March 2026",
    "bullets": [
      "Feature A released",
      "Feature B released"
    ],
    "link": "products/new-product/README.md",
    "subdir": "products/new-product"
  }
]

8. Security Configuration

8.1 HTTP Security Headers

Header	Value	Purpose
`X-Frame-Options`	`SAMEORIGIN`	Prevents clickjacking
`X-Content-Type-Options`	`nosniff`	Prevents MIME sniffing
`X-XSS-Protection`	`1; mode=block`	XSS attack prevention
`Referrer-Policy`	`no-referrer-when-downgrade`	Referrer leakage control

8.2 Access Control

Control	Status	Details
HTTPS	Enforced	Let’s Encrypt via Certbot, auto-renewal
Dotfile blocking	Active	Nginx denies `location ~ /\.`
Basic auth	Configured (inactive)	Per-section `.htpasswd` ready in nginx config
IP whitelist	Configured (inactive)	Per-section IP restriction ready
Repository	Private	GitHub private repo with token auth

8.3 Caching Strategy

Asset Type	Cache Duration	Headers
Images (jpg, png, gif, ico, svg)	1 year	`Cache-Control: public, immutable`
CSS, JS	1 year	`Cache-Control: public, immutable`
Fonts (woff, woff2, ttf, eot)	1 year	`Cache-Control: public, immutable`
HTML pages	No cache header	Served fresh (nginx default)

8.4 Compression

Setting	Value
Gzip	Enabled
Compression level	6
Content types	text/plain, text/css, text/xml, text/javascript, application/json, application/javascript, application/xml+rss, application/atom+xml, image/svg+xml

9. Markdown Extensions Reference

Complete inventory of enabled markdown extensions and their syntax:

9.1 Python Markdown (Standard)

Extension	Syntax Example	Purpose
`abbr`	`*[HTML]: HyperText Markup Language`	Abbreviation tooltips
`admonition`	`!!! note "Title"`	Callout boxes
`attr_list`	`{ .class #id }`	HTML attributes on elements
`def_list`	`Term\n: Definition`	Definition lists
`footnotes`	`[^1]` / `[^1]: Text`	Footnote references
`md_in_html`	`<div markdown>`	Markdown inside HTML blocks
`tables`	`	col
`toc`	Auto-generated	Table of contents (3-level, permalink anchors)

9.2 PyMdown Extensions (Enhanced)

Extension	Syntax Example	Purpose
`arithmatex`	$E = mc^2$	LaTeX math rendering
`betterem`	`bold _italic_`	Improved emphasis handling
`caret`	`^^superscript^^`	Superscript text
`details`	`??? note "Click"`	Collapsible sections
`emoji`	`:material-home:` `:octicons-arrow-right-24:`	8000+ icons (Material + Octicons)
`highlight`	```python ... ```	Syntax highlighting (Pygments)
`inlinehilite`	`#!python 3+4`	Inline code highlighting
`keys`	`++ctrl+c++`	Keyboard key display
`mark`	`==highlighted==`	Text highlighting
`smartsymbols`	`(c) (tm) -->`	Smart typography
`superfences`	```mermaid ... ```	Fenced code + Mermaid diagrams
`tabbed`	`=== "Tab 1"`	Content tabs
`tasklist`	`- [x] Done`	Checkbox task lists
`tilde`	`~~strikethrough~~` / `~subscript~`	Strikethrough + subscript

10. Configuration Files Reference

10.1 mkdocs.yml (Complete Schema)

# Site metadata
site_name: "iSu Technologies Documentation"
site_url: "https://docs.isutech.co.za"
site_author: "iSu Technologies Team"
site_description: "Central documentation hub..."
repo_url: "https://github.com/gedeza/isutech-knowledge-hub"
repo_name: "gedeza/isutech-knowledge-hub"
edit_uri: "edit/main/docs/"
copyright: "Copyright © 2025 iSu Technologies (Pty) Ltd"
docs_dir: "docs"
site_dir: "site"
strict: false

# Theme
theme:
  name: material
  language: en
  palette: [light + dark with toggle]
  font: {text: Roboto, code: Roboto Mono}
  features: [21 features enabled — see Section 4]
  logo: assets/images/isutech-logo.png
  favicon: assets/images/isutech-logo.png
  icon: {repo: github, edit: pencil, view: eye}

# Navigation: 13 top-level sections (see Section 4.4)

# Plugins
plugins:
  - search: {lang: en, separator: '[\s\-\.]+'}
  - git-revision-date-localized: {enable_creation_date: true, type: date}
  - minify: {minify_html: true, minify_js: true, minify_css: true, htmlmin_opts: {remove_comments: true}}

# Extensions: 20+ markdown extensions (see Section 9)

# Extra
extra:
  social: [{github}, {website}]
  version: {provider: mike}
extra_css: [stylesheets/extra.css]

10.2 .gitignore

venv/ __pycache__/ *.py[cod] *.so *.egg dist/ build/
site/ .cache/
.vscode/ .idea/ *.swp *.swo *~ .DS_Store
.env .env.local
*.log *.tmp *.temp .temp/
*.bak *.backup
Thumbs.db

10.3 Nginx Configuration (nginx-docs.conf)

See Section 8 for full security and caching details.

Key directives:

server_name docs.isutech.co.za;
root /var/www/docs/repo/site;
try_files $uri $uri/ =404;
# + security headers, gzip, caching, dotfile blocking

11. Platform Migration Guide

11.1 Migration Decision Matrix

Factor	MkDocs Material	Docusaurus	Starlight (Astro)	Sphinx	GitBook
Language	Python	JavaScript/React	JavaScript/Astro	Python	SaaS
Content format	Markdown	MDX (Markdown + JSX)	Markdown + MDX	reStructuredText + Markdown	Markdown
Search	Lunr.js (client)	Algolia or local	Pagefind (client, zero-config)	Sphinx search	Built-in
Dark mode	Built-in toggle	Built-in toggle	Built-in toggle (auto)	Theme-dependent	Built-in
Diagrams	Mermaid	Mermaid	Mermaid (via plugin)	Mermaid/Graphviz	Mermaid
Custom components	CSS + HTML-in-MD	React components	Astro components (HTML+JS islands)	Directives	Limited
Versioning	mike	Built-in	Manual (multi-deploy)	Built-in	Built-in
Build speed	~55s for 251 docs	Faster (incremental)	Fastest (partial hydration, ~15-25s)	Similar	N/A (SaaS)
Self-hosted	Yes	Yes	Yes	Yes	No (SaaS)
Hosting cost	$0 (static files)	$0 (static files)	$0 (static files)	$0 (static files)	$8+/user/mo
JS shipped to client	Minimal (theme JS)	Heavy (~300KB React runtime)	Near-zero (islands architecture)	Minimal	N/A
i18n	Plugin-based	Built-in	Built-in (first-class)	Built-in	Built-in
TypeScript support	N/A	Full	Full (type-safe config)	N/A	N/A
Component framework	None	React only	Any (React, Vue, Svelte, Solid, none)	None	None
Ecosystem maturity	Mature (2014+)	Mature (2017+)	Growing (2023+)	Very mature (2008+)	Mature (SaaS)

11.2 Migration to Docusaurus

Effort estimate: 2-3 days

Step 1: Project Setup

npx create-docusaurus@latest docshub classic --typescript

Step 2: Content Migration

Copy docs/ directory as-is (Docusaurus reads .md natively)
Rename README.md files to index.md (Docusaurus convention)
Convert mkdocs.yml nav to sidebars.js:

// sidebars.js (generated from mkdocs.yml nav)
module.exports = {
  docs: [
    {type: 'category', label: 'Home', items: [
      'index', '00-INDEX/GETTING_STARTED', '00-INDEX/USER_GUIDE',
      '00-INDEX/ADMIN_GUIDE', '00-INDEX/DOCUMENT_STANDARDS',
    ]},
    {type: 'category', label: 'About', items: [
      'about/company-overview', 'about/metrics-showcase', 'about/tech-stack',
    ]},
    // ... continue for all 13 sections
  ],
};

Step 3: Feature Parity Mapping

MkDocs Feature	Docusaurus Equivalent
`!!! note` admonitions	`:::note` / `:::tip` etc.
`=== "Tab"` content tabs	`<Tabs>` + `<TabItem>` components
`:material-icon:` icons	Install `@iconify/react` or use emojis
`<div class="grid cards">`	Custom React `<CardGrid>` component
`pymdownx.superfences` mermaid	`@docusaurus/theme-mermaid`
`git-revision-date`	`showLastUpdateTime: true`
`extra.css` custom styles	`src/css/custom.css`
Marker-comment auto-update	Modify `update-frontpage.py` to target `src/pages/index.tsx`

Step 4: Theme/Branding

Port CSS variables to src/css/custom.css
Recreate glassmorphism cards as React component
Port responsive breakpoints

Step 5: Build Integration

Replace mkdocs build --clean with npm run build in update-docs.sh
Adjust nginx.conf root to build/ instead of site/

11.3 Migration to Starlight (Astro)

Effort estimate: 2-3 days

Why consider Starlight: Starlight is Astro’s purpose-built documentation framework. It ships near-zero JavaScript to the client (islands architecture), has built-in i18n, Pagefind search (no external service), and the fastest build times of any SSG. It’s the strongest modern alternative to MkDocs Material for content-heavy documentation sites.

Step 1: Project Setup

npm create astro@latest -- --template starlight docshub
cd docshub

This scaffolds a complete Starlight project with:

astro.config.mjs — site config (equivalent to mkdocs.yml)
src/content/docs/ — content directory (equivalent to docs/)
src/assets/ — images and static files
src/styles/ — custom CSS

Step 2: Content Migration

Copy all docs/**/*.md files to src/content/docs/
Rename README.md files to index.md (Starlight convention)
Add frontmatter to each file (Starlight requires title: at minimum):

---
title: Company Overview
description: iSu Technologies company overview and metrics
---
# existing content here...

Convert mkdocs.yml nav to astro.config.mjs sidebar:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'iSu Technologies Documentation',
      logo: {
        src: './src/assets/isutech-logo.png',
      },
      social: {
        github: 'https://github.com/gedeza/isutech-knowledge-hub',
      },
      editLink: {
        baseUrl: 'https://github.com/gedeza/isutech-knowledge-hub/edit/main/docs/',
      },
      sidebar: [
        {
          label: 'Home',
          items: [
            { label: 'Getting Started', slug: '00-index/getting-started' },
            { label: 'User Guide', slug: '00-index/user-guide' },
            { label: 'Admin Guide', slug: '00-index/admin-guide' },
            { label: 'Document Standards', slug: '00-index/document-standards' },
          ],
        },
        {
          label: 'About',
          items: [
            { label: 'Company Overview', slug: 'about/company-overview' },
            { label: 'Metrics & Impact', slug: 'about/metrics-showcase' },
            { label: 'Technology Stack', slug: 'about/tech-stack' },
          ],
        },
        // ... continue for all 13 sections
        {
          label: 'Products',
          autogenerate: { directory: 'products' },
        },
        {
          label: 'Prospects',
          autogenerate: { directory: 'prospects' },
        },
      ],
      customCss: ['./src/styles/custom.css'],
    }),
  ],
});

Step 3: Feature Parity Mapping

MkDocs Feature	Starlight Equivalent
`!!! note` admonitions	`:::note` / `:::tip` / `:::caution` / `:::danger` (built-in Asides)
`=== "Tab"` content tabs	`<Tabs>` + `<TabItem>` components (built-in)
`:material-icon:` icons	`<Icon name="star" />` component (built-in, uses `@iconify`) or install `starlight-icon-badges`
`<div class="grid cards">`	`<CardGrid>` + `<Card>` components (built-in)
`pymdownx.superfences` mermaid	`astro-diagram` integration or `<Code>` with custom renderer
`git-revision-date`	`lastUpdated: true` in config (built-in, uses git)
`extra.css` custom styles	`customCss: ['./src/styles/custom.css']` in config
Dark/light toggle	Built-in (auto-detects OS preference + manual toggle)
Full-text search	Pagefind — zero-config, built-in, no external service
Marker-comment auto-update	Modify `update-frontpage.py` to target `src/content/docs/index.md`
`md_in_html`	Use `.mdx` extension — full component support in markdown
Code copy button	Built-in with `<Code>` component
Table of contents	Built-in right sidebar TOC
Breadcrumbs	Built-in
Edit on GitHub	`editLink.baseUrl` in config

Step 4: Built-in Components (No Plugins Needed)

Starlight ships these components out of the box — no extra packages:

---
title: Example Page
---
import { Card, CardGrid, Tabs, TabItem, LinkCard, Aside, Badge, Icon, Steps } from '@astrojs/starlight/components';

<CardGrid>
  <Card title="ThriveSend B2B2G" icon="rocket">
    7 production-ready marketing channels.
    [View Docs →](/products/thrive-send-b2b2g/)
  </Card>
  <Card title="Security Hardening" icon="shield">
    Comprehensive server security documentation.
  </Card>
</CardGrid>

<Tabs>
  <TabItem label="Email">Resend integration...</TabItem>
  <TabItem label="SMS">Twilio integration...</TabItem>
</Tabs>

:::note[Important]
This is a built-in aside/admonition — no plugin required.
:::

<Steps>
1. Clone the repository
2. Install dependencies
3. Run the build
</Steps>

Step 5: Theme/Branding

Port CSS variables to src/styles/custom.css:

:root {
  --sl-color-accent-low: #996515;
  --sl-color-accent: #B8860B;
  --sl-color-accent-high: #DAA520;
  --sl-color-white: #ffffff;
  --sl-color-gray-1: #f3f4f6;
  --sl-color-gray-5: #1a1a1a;
  --sl-font: 'Roboto', sans-serif;
  --sl-font-mono: 'Roboto Mono', monospace;
}

/* Starlight uses CSS custom properties extensively — */
/* override these instead of writing selectors from scratch */
:root[data-theme='dark'] {
  --sl-color-accent-low: #DAA520;
  --sl-color-accent: #B8860B;
  --sl-color-accent-high: #996515;
}

Starlight’s theming is simpler than Material — most visual customisation is done through ~20 CSS custom properties rather than 1,256 lines of selector overrides.

Step 6: Custom Astro Components for Advanced UI

For DocsHub’s custom components (hero, timeline, ROI calculator, etc.), create Astro components:

src/
├── components/
│   ├── Hero.astro           # Hero section with auto-stats
│   ├── MetricCard.astro     # KPI display cards
│   ├── Timeline.astro       # Gold timeline component
│   ├── ROICalculator.astro  # Interactive ROI display
│   ├── TechStack.astro      # Tech pill badges
│   └── Testimonial.astro    # Quote blocks

Astro components are pure HTML + CSS + scoped JS — no framework runtime shipped to the client:

---
const { value, label } = Astro.props;
---
<div class="metric-card">
  <span class="metric-large">{value}</span>
  <span class="metric-label">{label}</span>
</div>

<style>
  .metric-card {
    text-align: center;
    padding: 1.5rem;
    border: 2px solid #e5e7eb;
    border-radius: 12px;
  }
  .metric-large {
    font-size: 2.5rem;
    font-weight: 700;
    color: var(--sl-color-accent);
  }
</style>

Step 7: Build Integration

Replace mkdocs build --clean with npm run build in update-docs.sh
Adjust nginx.conf root to dist/ instead of site/
Add package.json to repo root with build scripts
Starlight build output is in dist/ by default

# update-docs.sh changes
npm ci --production          # install deps (cached, fast)
npm run build                # astro build → dist/

Step 8: Mermaid Diagrams

Install the Mermaid integration:

npx astro add @astrojs/starlight-mermaid

Or use the community remark-mermaidjs plugin in astro.config.mjs.

Starlight Advantages over MkDocs Material:

Advantage	Detail
Build speed	Astro’s partial hydration = ~15-25s for 250+ docs vs ~55s
Client JS	Ships ~0KB JS by default (islands opt-in) vs ~150KB
Search	Pagefind runs at build time, no external service, ~5KB client
i18n	First-class multi-language with route-based locale prefixes
Components	Use any framework (React, Vue, Svelte) or none — Astro components are zero-JS
Type safety	Content collections with Zod schema validation for frontmatter
Modern tooling	Vite-based dev server with HMR, TypeScript throughout

Starlight Limitations vs MkDocs Material:

Limitation	Detail
Ecosystem maturity	Newer (2023) — fewer plugins than MkDocs or Docusaurus
Icon library	Doesn’t ship 8000+ Material icons by default — use `@iconify`
Versioning	No built-in doc versioning (requires multi-deploy strategy)
Python ecosystem	Requires Node.js — different stack from current setup
Community size	Smaller community than Docusaurus or MkDocs (but growing fast)

11.4 Migration to Sphinx

Effort estimate: 3-5 days (RST conversion is the main cost)

Step 1: Project Setup

pip install sphinx sphinx-immaterial myst-parser
sphinx-quickstart

Step 2: Content Migration

Option A: Use myst-parser to keep Markdown files (recommended)
Option B: Convert .md to .rst using pandoc --from=markdown --to=rst
Convert mkdocs.yml nav to toctree directives in each index.rst

Step 3: Feature Parity

MkDocs Feature	Sphinx Equivalent
Material theme	`sphinx-immaterial` theme
Admonitions	`.. note::` directives (native)
Mermaid	`sphinxcontrib-mermaid`
Search	Built-in Sphinx search
Git dates	`sphinx-last-updated-by-git`
Tabs	`sphinx-tabs` or `sphinx-design`
Cards	`sphinx-design` card directive

Step 4: Build Integration

Replace mkdocs build with sphinx-build -b html docs/ site/

11.5 Migration Checklist (Any Platform)

Use this checklist regardless of target platform:

12. Operational Procedures

12.1 Adding a New Document

Create .md file in appropriate docs/ subdirectory
Follow naming convention: lowercase-with-hyphens.md
Add to nav: section in mkdocs.yml
Commit and push to main
Wait up to 10 minutes for auto-deploy (or trigger manually)

12.2 Adding a New Product

Create directory: docs/products/<product-name>/
Create README.md as section index
Add product documents (product-brief, demo-script, etc.)
Add nav section under Products: in mkdocs.yml
Add directory mapping to update-frontpage.py (DIR_ICON_MAP, DIR_TITLE_MAP)
Product count on front page auto-updates on next build

12.3 Adding a New Prospect

Create directory: docs/prospects/<prospect-name>/
Copy standard document set (see Section 6.4)
Add nav section under Prospects & Opportunities: in mkdocs.yml
Add directory mapping to update-frontpage.py

12.4 Manual Build Trigger

cd /var/www/docs/repo
source /var/www/docs/venv/bin/activate
python3 deployment/update-frontpage.py --verbose
mkdocs build --clean

12.5 Monitoring

Check	Command	Expected
Site accessible	`curl -sI https://docs.isutech.co.za`	HTTP 200
SSL valid	`echo \| openssl s_client -connect docs.isutech.co.za:443 2>/dev/null \| openssl x509 -dates`	Not expired
Build logs	`tail -20 /var/log/docs-update.log`	”Completed Successfully”
Nginx logs	`tail -20 /var/log/nginx/docs-error.log`	No errors
Disk usage	`du -sh /var/www/docs/repo/site/`	~44 MB

12.6 Troubleshooting

Symptom	Likely Cause	Fix
Site shows old content	Cron not running	Check `crontab -l`, verify script path
Build fails	Broken markdown/YAML	Check `tail -50 /var/log/docs-update.log`
404 on pages	Page not in nav	Add to `mkdocs.yml` nav section
Search not working	Index stale	Run `mkdocs build --clean`
SSL expired	Certbot renewal failed	`certbot renew --dry-run`, check timer
Slow page loads	Cache misconfigured	Verify nginx cache headers

13. File Manifest

Complete inventory of every configuration and infrastructure file:

File	Purpose	Lines
`mkdocs.yml`	Site generator configuration	429
`requirements.txt`	Python dependencies	3
`.gitignore`	Git exclusion rules	41
`docs/stylesheets/extra.css`	Custom branding and components	1,256
`docs/index.md`	Front page with auto-update markers	~407
`docs/assets/images/isutech-logo.png`	Brand logo	—
`deployment/update-docs.sh`	Cron build script	56
`deployment/update-frontpage.py`	Dynamic front page generator	~400
`deployment/nginx-docs.conf`	Nginx site configuration	73
`deployment/DEPLOYMENT_CHECKLIST.md`	16-section deployment checklist	—
`deployment/MAINTENANCE_GUIDE.md`	Monthly maintenance procedures	515
`deployment/README.md`	Deployment overview	—

14. Performance Targets

Metric	Target	Current
Page load time	< 2 seconds	Met (static site + CDN-capable)
Build time	< 120 seconds	~55 seconds
Uptime	> 99.9%	Met (static files, minimal failure modes)
Auto-update latency	< 10 minutes	10-minute cron cycle
Search response	< 200ms	Met (client-side Lunr.js)

15. Future Considerations

Enhancement	Complexity	Notes
GitHub Actions CI/CD	Low	Replace cron with webhook-triggered builds
Algolia DocSearch	Low	Better search UX with server-side index
Google Analytics	Low	Uncomment `analytics:` in mkdocs.yml
Doc versioning	Medium	Activate `mike` for v1/v2/latest
PDF export	Medium	`mkdocs-pdf-export-plugin`
Auth per section	Low	Uncomment nginx basic auth blocks
Multi-repo sync	Medium	Extend ThriveSend sync pattern to other products
Automated testing	Medium	Link checker, markdown linting in CI
i18n	High	Multi-language support (Material supports it)

This document is maintained alongside the DocsHub codebase. When infrastructure changes, update this document to keep it accurate for future migrations.

DocsHub Technical Design Document

DocsHub Technical Design Document

1. Executive Summary

2. System Architecture Overview

2.1 Architecture Diagram

2.2 Deployment Topology

3. Technology Stack

3.1 Current Stack (MkDocs Material)

3.2 Python Dependencies (requirements.txt)

3.3 Stack Decision Rationale

4. Feature & Function Specifications

4.1 Feature Inventory

F-001: Full-Text Client-Side Search

F-002: Light/Dark Mode Toggle

F-003: Instant Navigation (SPA-like)

F-004: Navigation System

F-005: Dynamic Front Page (Auto-Updated)

F-006: Git-Based “Last Updated” Dates

F-007: Mermaid Diagrams

F-008: Code Syntax Highlighting

F-009: Admonitions (Callout Boxes)

F-010: Content Tabs

F-011: Material Grid Cards

F-012: Task Lists

F-013: Keyboard Shortcuts Display

F-014: Math/LaTeX Rendering

F-015: Abbreviations & Glossary

F-016: Footnotes

F-017: Edit/View Source Links

F-018: Social Links (Footer)

F-019: Versioning Support (Configured)

F-020: HTML Minification

F-021: Print Stylesheet

4.2 Custom UI Components (CSS)

5. Brand Design System

5.1 Color Palette

5.2 Typography

5.3 Spacing & Layout

5.4 Responsive Breakpoints

5.5 Visual Effects

5.6 Assets

6. Content Architecture

6.1 Content Statistics

6.2 Content Taxonomy

6.3 Document Standards

6.4 Prospect Document Pattern

7. Deployment Pipeline

7.1 Build Pipeline Flow

7.2 update-docs.sh (Build Script)

7.3 update-frontpage.py (Dynamic Content Generator)

7.4 Changelog Override Format

8. Security Configuration

8.1 HTTP Security Headers

8.2 Access Control

8.3 Caching Strategy

8.4 Compression

9. Markdown Extensions Reference

9.1 Python Markdown (Standard)

9.2 PyMdown Extensions (Enhanced)

10. Configuration Files Reference

10.1 mkdocs.yml (Complete Schema)

10.2 .gitignore

10.3 Nginx Configuration (nginx-docs.conf)

11. Platform Migration Guide

11.1 Migration Decision Matrix

11.2 Migration to Docusaurus

11.3 Migration to Starlight (Astro)

11.4 Migration to Sphinx

11.5 Migration Checklist (Any Platform)

12. Operational Procedures

12.1 Adding a New Document

12.2 Adding a New Product

12.3 Adding a New Prospect

12.4 Manual Build Trigger

12.5 Monitoring

12.6 Troubleshooting

13. File Manifest

14. Performance Targets

15. Future Considerations