CodeSlick Wiki Documentation Setup¶

Date: November 4, 2025 Status: Ready to implement

Why Wiki Documentation?¶

Problem: 52+ markdown files becoming hard to search and navigate.

Solution: MkDocs with Material theme - a searchable, beautiful documentation site.

Quick Start (5 minutes)¶

1. Install MkDocs¶

# Install MkDocs and Material theme
pip install mkdocs-material

# Verify installation
mkdocs --version
# Should show: mkdocs, version 1.5.x

2. Run Local Server¶

# From project root
mkdocs serve

# Open browser to: http://127.0.0.1:8000

You'll see a beautiful, searchable documentation site with: - ✅ Instant full-text search - ✅ Dark/light mode toggle - ✅ Responsive mobile design - ✅ Code syntax highlighting - ✅ Navigation sidebar

3. Test Search¶

Try searching for: - "stripe webhook" - "member limits" - "Phase 4 Week 2" - "OWASP Top 10"

Results appear instantly as you type!

Project Structure¶

codeslick2/
├── docs/                          # Documentation source
│   ├── index.md                   # Homepage
│   ├── overview.md                # Project overview
│   ├── quickstart.md              # Getting started
│   ├── business/                  # Business docs
│   │   ├── option-a-model.md
│   │   ├── pricing.md
│   │   └── beta-testing.md
│   ├── phases/                    # Implementation phases
│   │   ├── phase-1-complete.md
│   │   ├── phase-2-complete.md
│   │   └── ...
│   ├── technical/                 # Technical guides
│   │   ├── stripe-setup.md
│   │   ├── database.md
│   │   └── ...
│   ├── operations/                # Operations
│   │   ├── production-readiness.md
│   │   └── monitoring.md
│   └── api/                       # API documentation
│       ├── overview.md
│       └── teams.md
├── mkdocs.yml                     # MkDocs configuration
└── [existing md files]            # Keep for now (migrate gradually)

Migration Strategy¶

Phase 1: Symlinks (Quick - Keep Both Systems)¶

Pros: No file duplication, both systems work Cons: Symlinks can be fragile

# Create docs directory structure
mkdir -p docs/{business,phases,technical,operations,api}

# Symlink existing files
ln -s ../OPTION_A_BUSINESS_MODEL.md docs/business/option-a-model.md
ln -s ../BETA_TESTING_GUIDE.md docs/business/beta-testing.md
ln -s ../PHASE_1_COMPLETE.md docs/phases/phase-1-complete.md
# ... etc

Phase 2: Copy + Organize (Recommended)¶

Pros: Clean structure, can reorganize content Cons: Duplicate files (but docs/ becomes source of truth)

# Copy and organize files
cp OPTION_A_BUSINESS_MODEL.md docs/business/option-a-model.md
cp BETA_TESTING_GUIDE.md docs/business/beta-testing.md
cp PRODUCTION_STRIPE_SETUP_GUIDE.md docs/technical/stripe-setup.md
cp PHASE_*_COMPLETE.md docs/phases/

# Update internal links to new structure
# Old: [Link](PHASE_1_COMPLETE.md)
# New: [Link](../phases/phase-1-complete.md)

Phase 3: Full Migration (Long-term)¶

Pros: Single source of truth, cleaner repo Cons: Most work upfront

# Move all docs to docs/ folder
# Delete root markdown files
# Update all references

Configuration Options¶

Enable Advanced Features¶

Edit mkdocs.yml:

# Add tags support
plugins:
  - search
  - tags          # Tag pages with keywords

# Add versioning (track doc changes over time)
  - mike:
      version_selector: true

# Add PDF export
  - pdf-export

# Add diagrams (Mermaid support)
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid

Customize Theme¶

theme:
  name: material
  palette:
    primary: indigo      # Change to your brand color
    accent: purple
  logo: assets/logo.png  # Add your logo

Deploy to Production¶

Option 1: GitHub Pages (Free)¶

# Build and deploy
mkdocs gh-deploy

# Accessible at: https://yourusername.github.io/codeslick2/

Option 2: Vercel (Recommended)¶

# In project root, create vercel.json:
{
  "buildCommand": "pip install mkdocs-material && mkdocs build",
  "outputDirectory": "site",
  "installCommand": "pip install mkdocs-material"
}

# Deploy
vercel --prod

# Accessible at: https://docs.codeslick.dev

Option 3: Netlify¶

# Create netlify.toml:
[build]
  command = "pip install mkdocs-material && mkdocs build"
  publish = "site"

# Deploy via Netlify CLI or dashboard

Usage Examples¶

Searching¶

Full-text search across all documentation: - Type in search bar → Instant results - Highlights matching terms - Shows context snippets - Can share search results via URL

Example searches: - "How do I setup Stripe?" → Opens PRODUCTION_STRIPE_SETUP_GUIDE.md - "What is Option A?" → Opens OPTION_A_BUSINESS_MODEL.md - "member limit enforcement" → Shows all relevant sections

Three ways to navigate:

Sidebar - Hierarchical navigation tree
Search - Instant full-text search
Tags - Tag pages with topics like #billing, #security, #phase4

Cross-Linking¶

Link between docs easily:

See [Stripe Setup](../technical/stripe-setup.md) for details.

Related: [Phase 4 Week 2](../phases/phase-4-week-2.md)

API Reference: [Teams API](../api/teams.md#create-team)

Alternative Options Compared¶

Feature	MkDocs	Docusaurus	Obsidian	Notion
Markdown-native	✅	✅	✅	❌
Full-text search	✅	✅	✅	✅
Stays in repo	✅	✅	❌	❌
Setup time	5 min	30 min	2 min	10 min
Deployment	Easy	Moderate	N/A	N/A
Version control	✅	✅	Manual	❌
Offline access	✅	✅	✅	❌
Collaboration	GitHub	GitHub	Limited	✅
Graph view	❌	❌	✅	❌
Custom styling	✅	✅	✅	❌
Cost	Free	Free	Free	$$$

Recommendation: MkDocs for best balance of simplicity, features, and integration.

Immediate Next Steps¶

1. Install and Preview (5 minutes)¶

# Install
pip install mkdocs-material

# Run local server
mkdocs serve

# Open: http://127.0.0.1:8000

2. Decide on Migration Strategy (5 minutes)¶

Choose one: - Quick: Use symlinks (keep both systems) - Recommended: Copy + organize (clean structure) - Long-term: Full migration (single source of truth)

3. Migrate First Batch (30 minutes)¶

Start with most-accessed docs:

# Business docs (most referenced)
cp OPTION_A_BUSINESS_MODEL.md docs/business/option-a-model.md
cp BETA_TESTING_GUIDE.md docs/business/beta-testing.md
cp PRODUCTION_STRIPE_SETUP_GUIDE.md docs/technical/stripe-setup.md

# Phase docs (comprehensive)
cp PHASE_*_COMPLETE.md docs/phases/

# Create placeholder index files
echo "# Business Documentation" > docs/business/index.md
echo "# Technical Guides" > docs/technical/index.md

4. Test Search (5 minutes)¶

Open http://127.0.0.1:8000 and search for: - "stripe webhook" - "member limits" - "Phase 4 Week 2"

Verify results appear instantly and are accurate.

Maintenance¶

Adding New Documentation¶

# 1. Create file in appropriate directory
touch docs/technical/new-guide.md

# 2. Add to mkdocs.yml navigation
nav:
  - Technical Guides:
      - New Guide: technical/new-guide.md

# 3. Preview changes
mkdocs serve

Updating Existing Docs¶

Just edit the markdown files in docs/ - changes reflect immediately when running mkdocs serve.

Keeping In Sync¶

If you keep both systems (root .md files + docs/ folder):

# Option 1: Manual sync
cp ROOT_FILE.md docs/appropriate/location.md

# Option 2: Use symlinks (automatic sync)
ln -s ../ROOT_FILE.md docs/appropriate/location.md

# Option 3: Script it
cat > sync-docs.sh <<'EOF'
#!/bin/bash
cp OPTION_A_BUSINESS_MODEL.md docs/business/option-a-model.md
cp BETA_TESTING_GUIDE.md docs/business/beta-testing.md
# ... add all mappings
EOF

chmod +x sync-docs.sh
./sync-docs.sh  # Run after updating root docs

FAQs¶

Q: Do I need to delete the root markdown files?¶

A: No! Keep both during transition: - Root files: Source of truth (easy to find for now) - docs/: Wiki structure (searchable, organized)

Migrate gradually over 1-2 weeks.

Q: Can I still edit files directly in repo?¶

A: Yes! MkDocs just reads markdown files. Edit with any text editor, VS Code, or directly in GitHub.

Q: What about images?¶

A: Store in docs/assets/:

![Architecture Diagram](../assets/architecture.png)

Q: Can I use Mermaid diagrams?¶

A: Yes! Already configured:

```mermaid
graph LR
    A[Free Plan] --> B{Need Team?}
    B -->|Yes| C[Upgrade to Team]
    B -->|No| D[Stay Free]
```

Q: How do I add tags to pages?¶

A: Add to frontmatter:

---
tags:
  - billing
  - stripe
  - payment
---

# Stripe Setup Guide
...

Support & Resources¶

MkDocs Docs: https://www.mkdocs.org
Material Theme: https://squidfunk.github.io/mkdocs-material
Examples: https://github.com/squidfunk/mkdocs-material/tree/master/docs

Conclusion¶

Recommendation: Start with MkDocs today.

Why: - ✅ 5-minute setup - ✅ Instant search across all docs - ✅ Beautiful, professional interface - ✅ Stays in your repo (version controlled) - ✅ Free and open source - ✅ Easy to maintain - ✅ Can deploy to production later

Not recommended (for your use case): - ❌ Notion/Confluence: Vendor lock-in, not markdown-native - ❌ Obsidian: Great for personal notes, but not for shared docs - ❌ Docusaurus: Overkill for solo developer, more complex setup

Next Step: Run pip install mkdocs-material && mkdocs serve and see it in action!