Documentation System - Complete Guide🔗

What This Is🔗

A simple, flexible documentation system for internal use. Write documents in Markdown, organize them with JSON, get a beautiful website.

Quick Start🔗

1. Setup (One Time)🔗

# Install required Python packages
pip install markdown pygments

2. Add Your Documents🔗

# Put .md files in the assets folder
assets/
  001.md  ← Your first document
  002.md  ← Your second document
  010.md  ← Another document

3. Configure🔗

Edit config.json to list your documents:

{
  "categories": [
    {
      "name": "Getting Started",
      "items": [
        {
          "type": "document",
          "file": "001.md",
          "title": "Introduction",
          "order": 1
        }
      ]
    }
  ]
}

4. Build🔗

# Windows
build_site.bat

# Or manually
python build_site.py

5. View🔗

Open index.html in your browser!

File Structure🔗

your-docs/
├── index.html              ← Generated home page
├── config.json             ← Your table of contents
├── build_site.py           ← Site builder
├── build_site.bat          ← Windows helper
├── md_to_html.py           ← Markdown converter
├── convert_md.vbs          ← Drag & drop converter
├── assets/                 ← All your .md files here
│   ├── 001.md
│   ├── 002.md
│   └── ...
└── README.md               ← This file

The config.json File🔗

This is the brain of your documentation system.

Basic Structure🔗

{
  "site": {
    "title": "Your Documentation Title",
    "subtitle": "Optional subtitle",
    "homeUrl": "index.html"
  },
  "categories": [
    {
      "id": "unique-id",
      "name": "Category Name",
      "description": "What this category contains",
      "project_number": "PRJ-2024-001",
      "items": [...]
    }
  ]
}

Document Entry🔗

{
  "type": "document",
  "file": "001.md",
  "title": "Document Title",
  "subtitle": "Short description",
  "date": "2026-02-02",
  "order": 1,
  "hidden": false,
  "note": "Internal note (not displayed)"
}

Fields:
- file - Filename in assets folder (required)
- title - Display title (required)
- subtitle - Short description (optional)
- date - Document date (optional)
- order - Sort order within category (optional)
- hidden - Hide from index (soft-delete, optional)
- note - Internal comment (optional)

Chapter (Nested Structure)🔗

{
  "type": "chapter",
  "name": "Chapter Name",
  "order": 1,
  "items": [
    {
      "type": "document",
      "file": "010.md",
      "title": "Sub-document",
      "order": 1
    }
  ]
}

Workflow🔗

Adding a New Document🔗

1. Create the .md file:
   bash assets/050.md

2. Write in Markdown:
   ```markdown
   # My New Document

## Introduction
Content here...
```

3. Add to config.json:
   json { "type": "document", "file": "050.md", "title": "My New Document", "order": 5 }

4. Rebuild:
   bash build_site.bat

Done!

Hiding a Document (Soft Delete)🔗

Don't delete the file or config entry. Just set hidden: true:

{
  "type": "document",
  "file": "098.md",
  "title": "Old Method",
  "hidden": true,
  "note": "Deprecated - kept for reference"
}

The file stays in assets/, but won't appear in the index.

Reordering Documents🔗

Just change the order values:

{
  "file": "001.md",
  "order": 5  ← Changed from 1
}

No need to rename or move files!

Creating Categories🔗

Add a new category object:

{
  "id": "new-category",
  "name": "New Category",
  "description": "Description here",
  "items": [...]
}

File Naming Strategy🔗

Use Numbers as Addresses🔗

Think of filenames as post box numbers:
- 001.md = permanent address
- 099.md = another permanent address
- Numbers don't need to be sequential

Don't: Rename files when reordering
Do: Change order in config.json

Benefits🔗

• ✓ File never moves (stable references)
• ✓ Content can change, address stays same
• ✓ Easy to reference: "See doc 012"
• ✓ No reorganization headaches

Features🔗

Responsive Design🔗

• ✓ Works on mobile, tablet, desktop
• ✓ Zoom-friendly (no horizontal scroll)
• ✓ Clean, readable typography

Navigation🔗

• ✓ Home link on every page (🏠 Home)
• ✓ Organized categories
• ✓ Nested chapters
• ✓ Table of contents in each document

Permalinks🔗

• ✓ Link emoji (🔗) on each heading
• ✓ Share direct links to sections
• ✓ Bookmark specific parts

Flexible Organization🔗

• ✓ Multiple hierarchy levels
• ✓ Custom ordering
• ✓ Rich metadata (dates, project numbers)
• ✓ Soft delete (hide without removing)

Publishing to Server🔗

Option 1: Upload Everything🔗

1. Build the site locally: build_site.bat
2. Upload these files to your server:
   - index.html
   - assets/ folder (with all .html files)
   - config.json (optional, for future rebuilds)

Option 2: Build on Server🔗

1. Upload:
   - config.json
   - build_site.py
   - md_to_html.py
   - assets/*.md files

2. Run on server:
   bash python build_site.py

Tips & Best Practices🔗

Writing Good Markdown🔗

• Use clear headings (# ## ###)
• Keep paragraphs short
• Use code blocks for examples
• Add bullet points for lists
• Include a table of contents naturally

Organizing Documents🔗

• Group related docs in same category
• Use chapters for hierarchical topics
• Keep categories focused (5-15 docs each)
• Use descriptive titles and subtitles

Maintenance🔗

• Review and update dates
• Mark outdated docs as hidden
• Add notes for context
• Keep config.json well-formatted

Performance🔗

• All files are static (fast loading)
• No database needed
• Works offline
• Easy to backup (just files)

Troubleshooting🔗

"Python not found"🔗

Install Python 3.6+ from python.org

"markdown module not found"🔗

pip install markdown pygments

Documents not appearing🔗

Check:
- File exists in assets/ folder
- Filename matches config.json
- hidden is not set to true
- Rebuild with build_site.bat

Navigation bar not showing🔗

Rebuild the site - nav bar is added during build

Horizontal scrolling on mobile🔗

Make sure you're using the updated md_to_html.py with responsive CSS

Advanced Usage🔗

Adding Project Numbers🔗

{
  "project_number": "PRJ-2024-001",
  "items": [...]
}

Shows in category header.

Multi-level Hierarchy🔗

{
  "type": "chapter",
  "name": "Main Topic",
  "items": [
    {
      "type": "chapter",
      "name": "Subtopic",
      "items": [
        {"type": "document", "file": "..."}
      ]
    }
  ]
}

Go as deep as needed.

Same Document, Multiple Categories🔗

Just reference it multiple times:

// Category 1
{"file": "050.md", "title": "Important Doc"}

// Category 2
{"file": "050.md", "title": "Important Doc"}

File stored once, appears twice.

Future Enhancements🔗

Possible additions:
- PDF download buttons
- Logo and branding
- Search functionality
- Dark mode
- Version history

But remember: Keep it simple! Only add what you actually need.

Support🔗

For questions or issues:
1. Check this README
2. Review the example config.json
3. Look at the two sample documents (001.md, 002.md)

Created: February 2, 2026
System: Markdown Documentation Generator
Version: 1.0