Skip to main content

CODITECT.AI Documentation Server - Navigation Guide

🌐 Server Features​

The custom Markdown server supports full subdirectory navigation with beautiful rendering!

✅ What You Can Do​

  1. Browse Directories - Navigate through folder structures
  2. View Markdown Files - Rendered as beautiful HTML pages
  3. View HTML Files - Served directly
  4. Clickable Breadcrumbs - Easy navigation back to parent folders
  5. File Icons - Visual indicators for file types
  6. Security - Directory traversal protection built-in

🗂️ Directory Navigation​

How to Navigate​

In Browser:

  1. Start at Root: http://localhost:8000/

    • You'll see a beautiful directory listing with file icons

  2. Click on Folders (📁):

    • Opens the directory listing for that folder
    • Shows all files and subdirectories inside

  3. Click on Files:

    • 📄 Markdown (.md) - Rendered as beautiful HTML
    • 🌐 HTML (.html) - Served directly
    • ⚙️ YAML (.yaml/.yml) - Downloaded
    • 🐍 Python (.py) - Downloaded

  4. Use Breadcrumbs:

    • Top of page shows: Home / folder1 / folder2
    • Click any part to jump back to that level

  5. Parent Directory Button:

    • ⬆️ Parent Directory button at top
    • Quick way to go back one level

📁 Example Directory Structure​

CODITECT-ARCHITECTURE/
├── index.html                  (🌐 HTML - served directly)
├── README.md                   (📄 Markdown - rendered as HTML)
├── coditect-platform-overview.md
├── coditect-gcp-gke-architecture.html
│
├── test-docs/                  (📁 Subdirectory)
│   ├── README.md
│   ├── guides/                 (📁 Nested subdirectory)
│   │   └── getting-started.md
│   └── api/
│       └── overview.md
│
├── kubernetes-config.yaml      (⚙️ YAML file)
└── socketio-chat-app.py       (🐍 Python file)

🎯 Navigation Examples​

Example 1: Reading a Nested Markdown File​

URL: http://localhost:8000/test-docs/guides/getting-started.md

What Happens:

  1. Server receives request for test-docs/guides/getting-started.md
  2. Checks it's a .md file ✅
  3. Reads the markdown content
  4. Converts to HTML with:
    • Syntax highlighting for code blocks
    • Styled tables
    • Beautiful typography
  5. Wraps in template with breadcrumb
  6. Sends to browser

You See:

  • Beautiful rendered markdown
  • Breadcrumb: Home / test-docs / guides / getting-started.md
  • "Back to Index" button
  • Properly highlighted code blocks

Example 2: Browsing a Subdirectory​

URL: http://localhost:8000/test-docs/

What Happens:

  1. Server detects test-docs/ is a directory
  2. Lists all files and folders inside
  3. Creates beautiful listing with icons
  4. Shows file sizes

You See:

  • 📄 README.md (2.1 KB)
  • 📁 guides/
  • 📁 api/
  • Each item is clickable
  • Breadcrumb: Home / test-docs

Example 3: Navigating Deep Paths​

Starting at: http://localhost:8000/test-docs/guides/getting-started.md

Navigation Options:

  1. Click "Back to Index" → Goes to http://localhost:8000/
  2. Click breadcrumb "guides" → Goes to http://localhost:8000/test-docs/guides/
  3. Click breadcrumb "test-docs" → Goes to http://localhost:8000/test-docs/
  4. Click breadcrumb "Home" → Goes to http://localhost:8000/
  5. Click "⬆️ Parent Directory" → Goes to http://localhost:8000/test-docs/guides/

🔒 Security Features​

Directory Traversal Protection​

The server prevents directory traversal attacks:

# This is BLOCKED:
http://localhost:8000/../../../etc/passwd

# Server checks that resolved path is within current directory
# Returns: 403 Forbidden - Access denied

Hidden File Protection​

Files starting with . are not listed in directory browsing:

.venv/          ← Hidden (not shown)
.git/           ← Hidden (not shown)
.gitignore      ← Hidden (not shown)
README.md       ← Visible ✅

📋 URL Patterns​

Valid URL Patterns​

URL PatternResultDescription
/Directory listingRoot directory
/folder/Directory listingBrowse folder
/file.mdRendered HTMLMarkdown file
/file.htmlServed directlyHTML file
/folder/subfolder/file.mdRendered HTMLNested markdown
/folder/subfolder/Directory listingNested directory

URL Normalization​

The server handles various URL formats:

# These all work the same:
http://localhost:8000/test-docs
http://localhost:8000/test-docs/
http://localhost:8000/test-docs/index

# These are equivalent:
http://localhost:8000/README.md
http://localhost:8000/./README.md

🎨 Visual Features​

File Type Icons​

  • 📁 Directories - Light blue/green background
  • 📄 Markdown (.md) - Light red/pink background
  • 🌐 HTML (.html) - Light orange/yellow background
  • ⚙️ YAML (.yaml/.yml) - Light green background
  • 🐍 Python (.py) - Light blue background
  • 📎 Other files - No background color
Home / test-docs / guides / getting-started.md
 ↑       ↑           ↑              ↑
 |       |           |              └─ Current file (bold)
 |       |           └─ Clickable link
 |       └─ Clickable link
 └─ Clickable link to root

Hover Effects​

  • Directory items - Slide right 5px on hover
  • Links - Color changes to purple gradient
  • Border - Changes from gray to purple

💻 Command Line Testing​

Test Directory Listing​

# Get root directory listing
curl http://localhost:8000/

# Get subdirectory listing
curl http://localhost:8000/test-docs/

# Get nested directory
curl http://localhost:8000/test-docs/guides/

Test Markdown Rendering​

# Render root markdown
curl http://localhost:8000/README.md | less

# Render nested markdown
curl http://localhost:8000/test-docs/guides/getting-started.md | less

Test Status Codes​

# Should return 200 OK
curl -I http://localhost:8000/README.md

# Should return 404 Not Found
curl -I http://localhost:8000/nonexistent.md

# Should return 403 Forbidden (if trying directory traversal)
curl -I http://localhost:8000/../../../etc/passwd

🚀 Advanced Usage​

Linking Between Markdown Files​

In your markdown, you can link to other files:

<!-- Relative link to file in same directory -->
See [Overview](overview.md)

<!-- Relative link to file in parent directory -->
See [Main README](../README.md)

<!-- Relative link to file in subdirectory -->
See [API Docs](api/overview.md)

<!-- Absolute link (from root) -->
See [README](/README.md)

Organizing Documentation​

Best practices:

docs/
├── README.md              # Overview of documentation
├── getting-started/       # Beginner guides
│   ├── README.md         # Index of getting started guides
│   ├── installation.md
│   └── quickstart.md
├── guides/                # User guides
│   ├── README.md
│   ├── authentication.md
│   └── deployment.md
├── api/                   # API documentation
│   ├── README.md
│   ├── rest-api.md
│   └── websocket-api.md
└── reference/             # Reference documentation
    ├── README.md
    ├── configuration.md
    └── troubleshooting.md

Each README.md in subdirectories:

  • Provides overview of that section
  • Links to files in that directory
  • Acts as index page

🔍 Troubleshooting​

Issue: Directory Not Loading​

Problem: Clicking folder doesn't show contents

Check:

# 1. Verify folder exists
ls -la test-docs/

# 2. Test URL directly
curl http://localhost:8000/test-docs/

# 3. Check permissions
ls -ld test-docs/

Solution: Ensure folder has read permissions

Issue: Markdown Not Rendering​

Problem: Markdown shows as plain text or downloads

Check:

# 1. Verify it's a .md file
ls -la test-docs/README.md

# 2. Check server logs
tail -50 /tmp/markdown-server.log

# 3. Test file extension
file test-docs/README.md

Solution: Ensure file has .md extension (lowercase)

Issue: 404 Not Found​

Problem: File exists but shows 404

Possible causes:

  1. Case sensitivity - README.md ≠ readme.md
  2. Spaces in path - URL encode: my file.md → my%20file.md
  3. Wrong path - Check breadcrumb for correct path

Test:

# List actual files
find . -name "*.md" -type f

# URL encode spaces
curl "http://localhost:8000/test-docs/my%20file.md"

📊 Server Logs​

View Access Logs​

# Watch logs in real-time
tail -f /tmp/markdown-server.log

# Search for specific path
grep "test-docs" /tmp/markdown-server.log

# See errors only
grep "Error" /tmp/markdown-server.log

Log Format​

[2025-10-20 10:30:45] GET /test-docs/README.md HTTP/1.1 200
[2025-10-20 10:30:46] GET /test-docs/guides/ HTTP/1.1 200
[2025-10-20 10:30:47] GET /nonexistent.md HTTP/1.1 404

🎓 Examples in Action​

Example Documentation Site​

Visit: http://localhost:8000/test-docs/

Structure:

test-docs/
├── README.md                    # Landing page
├── guides/                      # User guides section
│   └── getting-started.md       # First guide
└── api/                         # API docs section
    └── overview.md              # API overview

Navigation Flow:

  1. Open http://localhost:8000/test-docs/ - See directory listing
  2. Click README.md - See overview with links
  3. Click link to guides - Navigate to guides directory
  4. Click getting-started.md - Read getting started guide
  5. Use breadcrumb to go back - Click "test-docs" in breadcrumb
  6. Navigate to API docs - Click api/ folder
  7. Read API docs - Click overview.md

🌟 Pro Tips​

  1. Create README.md in every directory - Acts as index page
  2. Use relative links - More portable than absolute paths
  3. Organize by topic - Create subdirectories for different topics
  4. Include navigation - Add "Next" and "Previous" links in docs
  5. Use consistent naming - Lowercase, hyphens instead of spaces
  6. Test links - Use relative links and test navigation
  7. Add images - Put in images/ subfolder, link relatively

📝 Summary​

The CODITECT.AI Documentation Server provides:

✅ Full directory navigation - Browse any folder depth ✅ Beautiful markdown rendering - Syntax highlighting, tables, styles ✅ Clickable breadcrumbs - Easy navigation back up the tree ✅ File type icons - Visual file type indicators ✅ Security - Directory traversal protection ✅ Responsive design - Works on all screen sizes ✅ One server - HTML and Markdown both supported

Start exploring: http://localhost:8000/

Last updated: October 20, 2025