plan.md

MkDocs Integration Plan for Skupper Website

Overview

Integrate MkDocs Material to provide enhanced sidebar navigation for documentation at https://skupper.io/docs/ while preserving the existing Transom-based site structure.

Current Situation

• Problem: Transom and MkDocs both want to process files in input/docs/
• Conflict: input/docs/index.md (MkDocs) vs input/docs/index.html.in (Transom)
• Transom limitation: ignored_file_patterns only matches filenames, not directory paths

Proposed Solution: Rename Directories

New Directory Structure

skupper-website/
├── doc-input/                # RENAMED: Transom source (main site)
│   ├── index.md
│   ├── main.css
│   ├── commands/
│   ├── concepts/
│   ├── community/
│   ├── examples/
│   ├── releases/
│   ├── resources/
│   ├── start/
│   └── v1/                   # V1 docs (preserved)
│       └── docs/
├── input/                    # REPURPOSED: MkDocs source directory
│   └── docs/                 # MkDocs content (already here!)
│       ├── index.md
│       ├── overview/
│       ├── install/
│       ├── kube-cli/
│       ├── kube-yaml/
│       ├── system-cli/
│       ├── system-yaml/
│       ├── console/
│       ├── troubleshooting/
│       └── api-docs/
├── output/                   # Build output
│   ├── index.html            # From Transom
│   ├── v1/                   # From Transom (preserved)
│   └── docs/                 # From MkDocs (overwrites)
└── mkdocs.yml

Why This Approach?

✅ Minimal changes: MkDocs already expects input/docs/ structure
✅ Clear naming: doc-input = Transom source, input = MkDocs source
✅ No config changes: mkdocs.yml stays as docs_dir: input/docs
✅ V1 preserved: Moves with doc-input/v1/

Build Process

1. Stage 1 - Transom: ./plano render

   • Processes doc-input/ → output/
   • Generates entire site including placeholder for /docs/
   • V1 docs remain untouched

2. Stage 2 - MkDocs: mkdocs build

   • Processes input/docs/ → output/docs/
   • Overwrites only the /docs/ directory
   • Adds Material theme with sidebar navigation

3. Combined: ./plano render_all

   • Runs both stages in sequence
   • Final output has Transom site + MkDocs docs

Configuration Changes

.plano.py

# Update input_dir reference
input_dir = "doc-input"  # Changed from "input"

@command
def render():
    """Render the site using Transom"""
    run(f"transom render {input_dir} output")

@command
def render_docs():
    """Render documentation using MkDocs"""
    run("mkdocs build")

@command  
def render_all():
    """Render entire site (Transom + MkDocs)"""
    render()      # Transom first
    render_docs() # MkDocs second (overwrites /docs/)

config/transom.py

# Update any hardcoded "input" references if needed
# Most likely no changes needed as Transom gets input_dir from command

mkdocs.yml

# NO CHANGES NEEDED!
docs_dir: input/docs
site_dir: output/docs
use_directory_urls: false

Migration Steps

1. Rename Transom input directory:

   git mv input doc-input

2. Move MkDocs files back to input/docs:

   mkdir -p input/docs
   mv doc-input/docs/* input/docs/
   # Remove now-empty doc-input/docs/
   rmdir doc-input/docs

3. Update .plano.py:

   • Change input_dir references to doc-input
   • Update render() command

4. Update any other references:

   • Check config/transom.py for hardcoded paths
   • Check .gitignore if it references input/
   • Check GitHub Actions workflow
   • Check Netlify config

5. Test build:

   ./plano render_all

6. Verify:

   • Main site works: output/index.html
   • V1 docs preserved: output/v1/docs/
   • V2 docs with sidebar: output/docs/index.html

Benefits

✅ Clean separation: Transom uses doc-input/, MkDocs uses input/
✅ Minimal config changes: mkdocs.yml unchanged
✅ Clear ownership: Each tool has its own source directory
✅ V1 preservation: V1 docs move with Transom content
✅ Sidebar navigation: MkDocs Material provides rich navigation
✅ Brand consistency: Custom theme reuses Skupper header/footer/CSS
✅ Intuitive naming: doc-input clearly indicates Transom source

Alternative Considered

Move MkDocs to docs/: Would require changing mkdocs.yml and is less intuitive since MkDocs conventionally uses docs/ as the output directory name, not source.

Recommendation

Proceed with renaming input/ → doc-input/ and repurposing input/ for MkDocs. This is the cleanest solution that:

• Minimizes configuration changes
• Clearly separates concerns
• Follows each tool's conventions
• Preserves all existing content

Next Steps

1. ✅ Get approval for this plan
2. Execute migration (rename directories, update configs)
3. Test build locally
4. Update CI/CD (GitHub Actions, Netlify)
5. Deploy and verify

---

Status: Awaiting approval
Date: 2026-02-23
Approach: Rename input/ → doc-input/, repurpose input/ for MkDocs

skupper-website-mkdocs.md

MkDocs MVP - Testing Instructions

What's Been Created

The MVP integrates MkDocs Material with the existing Transom-based Skupper website to provide sidebar navigation for the V2 documentation.

Files Created/Modified

1. mkdocs.yml - MkDocs configuration

   • Configures Material theme
   • Defines navigation structure for V2 docs
   • Sets up markdown extensions and plugins

2. config/mkdocs_macros.py - Variable substitution

   • Reads from input/data/releases.json (same as Transom)
   • Provides {{skupper_cli_version}} and other variables
   • Ensures consistency with main site

3. .plano.py - Updated build commands

   • render_docs() - Renders docs with MkDocs
   • render_all() - Renders entire site (Transom + MkDocs)

Testing the MVP

Prerequisites

# Ensure you have Python 3.8+ and pip installed
python --version

# Install dependencies
pip install mkdocs-material mkdocs-macros-plugin

Step 1: Test MkDocs Only

Test that MkDocs can build the documentation:

# Build docs only (without Transom)
mkdocs build --clean

# Check output
ls -la output/docs/

Expected Result:

• output/docs/ directory created
• Contains HTML files with Material theme
• Sidebar navigation visible

Step 2: Test Full Build

Test the complete build process (Transom + MkDocs):

# Build everything
./plano render_all

# Or use individual commands
./plano render        # Transom only
./plano render_docs   # MkDocs only

Expected Result:

• output/ directory contains full site
• output/v1/ exists (Transom-rendered V1 docs)
• output/docs/ exists (MkDocs-rendered V2 docs with sidebar)

Step 3: Verify V1 Preservation

Check that V1 documentation is NOT overwritten by MkDocs:

# Check V1 exists
ls -la output/v1/

# Check V1 files are HTML (not markdown)
file output/v1/index.html

# Verify V1 has Transom styling (not Material theme)
grep -l "Transom" output/v1/index.html || echo "V1 preserved correctly"

Expected Result:

• output/v1/ directory exists
• Contains Transom-rendered HTML files
• Does NOT have Material theme styling

Step 4: Test Variable Substitution

Check that Transom variables work in MkDocs:

# Check that version variables are substituted
grep -r "{{skupper_cli_version}}" output/docs/

# Should return NO results (variables should be replaced)
# If it returns results, variables are not being substituted

Expected Result:

• No {{skupper_cli_version}} in output files
• Version numbers appear as actual values (e.g., "2.1.1")

Step 5: Serve Locally

Test the site locally:

# Serve with MkDocs (docs only)
mkdocs serve

# Open browser to http://localhost:8000

Expected Result:

• Documentation loads with sidebar navigation
• Material theme styling visible
• Navigation works
• Search works

Step 6: Visual Inspection

Open the generated files in a browser:

# Open main site
open output/index.html

# Open V1 docs
open output/v1/index.html

# Open V2 docs
open output/docs/index.html

Check:

• ✅ Main site looks normal (Transom styling)
• ✅ V1 docs look normal (Transom styling)
• ✅ V2 docs have Material theme with sidebar
• ⚠️ V2 docs styling may differ from main site (expected in MVP)

Known MVP Limitations

1. CSS Not Aligned: V2 docs use default Material theme, not Skupper branding
2. No Custom Header/Footer: V2 docs use Material's default header/footer
3. Navigation Incomplete: Some pages may not be in the nav tree yet
4. No Search Integration: Search only works within docs, not site-wide

These will be addressed in the refinement phase.

Troubleshooting

Error: "Module 'mkdocs_macros' not found"

pip install mkdocs-macros-plugin

Error: "No module named 'transom'"

# Make sure you're in the project root
cd /path/to/skupper-website

# Check Python path includes the project
export PYTHONPATH="${PYTHONPATH}:$(pwd)/python"

Variables Not Substituting

Check that input/data/releases.json exists:

ls -la input/data/releases.json

# If missing, generate it
./plano generate_releases

V1 Directory Missing

Make sure Transom runs first:

./plano render        # Run Transom first
./plano render_docs   # Then run MkDocs

Next Steps

After MVP validation:

1. CSS Alignment - Match Skupper branding
2. Custom Templates - Add Skupper header/footer
3. Complete Navigation - Add all doc pages
4. Testing - Visual regression tests
5. Documentation - Update main README

Success Criteria

The MVP is successful if:

• ✅ MkDocs builds without errors
• ✅ V2 docs have sidebar navigation
• ✅ V1 docs are preserved (not overwritten)
• ✅ Variables substitute correctly
• ✅ Site serves locally
• ✅ No broken links in docs

Questions or Issues?

Refer to mkdocs-plan.md for the complete integration plan and design decisions.