Skip to main content

theia Documentation Web Server

Status: ✅ Running on http://localhost:5000 (inside Docker container)

🚀 Quick Start​

The documentation server is currently running inside the Docker container!

Option 1: Access from Docker Container (Easiest)​

# SSH into the Docker container
docker exec -it claude-code-dev bash

# The server is already running! Check the logs:
cd /home/hal/v4/PROJECTS/t2/theia-research
tail -f server.log

# Server is accessible at:
# http://localhost:5000 (from inside the container)
# http://127.0.0.1:5000 (from inside the container)
# http://172.18.0.2:5000 (from inside the container)

Option 2: Port Forward to Windows Host​

To access the server from your Windows browser, you need to expose port 5000:

Method A: Restart Container with Port Mapping​

  1. Stop the current container:
docker stop claude-code-dev
  1. Start with port mapping:
docker run -d \
  --name claude-code-dev \
  -p 5000:5000 \
  -v C:/Users/Hal/v4:/home/hal/v4 \
  [other existing flags...] \
  [image name]
  1. Restart the server:
docker exec -it claude-code-dev bash
cd /home/hal/v4/PROJECTS/t2/theia-research
source venv/bin/activate
python serve_docs.py
  1. Access from Windows browser:
http://localhost:5000

Add to docker-compose.yml:

services:
  claude-dev:
    ports:
      - "5000:5000"

Then restart:

docker-compose down
docker-compose up -d

Method C: SSH Tunnel (Quick & Easy)​

From Windows PowerShell/CMD:

docker exec -it claude-code-dev bash -c "cd /home/hal/v4/PROJECTS/t2/theia-research && source venv/bin/activate && python serve_docs.py"

This runs the server in the foreground. Then access:

http://localhost:5000

📖 Features​

🎨 Beautiful UI​

  • GitHub-style markdown rendering
  • Syntax highlighting for all code blocks (TypeScript, Python, JSON, Bash)
  • Responsive design (mobile-friendly)
  • Dark header with clean white content area

🔗 Full Navigation​

  • Sidebar with quick links to key documentation
  • All internal crosslinks work (2,585 links)
  • Browse by directory (docs/, pages/)
  • Hash fragment support (e.g., #section-name)

🖼️ Images​

  • All 43 images properly served
  • Diagrams and screenshots display correctly
  • Architecture visualizations

📄 Metadata​

  • Source URL shown for each page
  • Crawl timestamp displayed
  • Links back to original theia-ide.org

🗺️ Navigation​

Homepage​

http://localhost:5000/

Loads the theia homepage

View Any Document​

http://localhost:5000/view/docs/architecture_ba3e2ea6.md
http://localhost:5000/view/docs/theia_ai_c6eb72b2.md
http://localhost:5000/view/pages/index_3fa68197.md

Browse Directories​

http://localhost:5000/browse/docs
http://localhost:5000/browse/pages

Key Documentation Pages​

PageURL
Homepage/ or /view/pages/index_3fa68197.md
Documentation Hub/view/docs/docs_eb80e882.md
Architecture/view/docs/architecture_ba3e2ea6.md
theia AI/view/docs/theia_ai_c6eb72b2.md
Services & Contributions/view/docs/services_and_contributions_1852f9bd.md
Widgets/view/docs/widgets_7ef2d829.md
Commands/Keybindings/view/docs/commands_keybindings_a18dc5cc.md
Authoring Extensions/view/docs/authoring_extensions_321e3e8e.md
User AI Guide/view/docs/user_ai_8b40c6db.md
theia Coder/view/docs/theia_coder_4f22850d.md

🛠️ Server Management​

Start Server (if not running)​

# Inside Docker container
cd /home/hal/v4/PROJECTS/t2/theia-research
source venv/bin/activate
python serve_docs.py

Start in Background​

# Inside Docker container
cd /home/hal/v4/PROJECTS/t2/theia-research
source venv/bin/activate
nohup python serve_docs.py > server.log 2>&1 &

Check if Running​

# Check process
ps aux | grep serve_docs.py

# Check logs
tail -f /home/hal/v4/PROJECTS/t2/theia-research/server.log

# Test with curl
curl -I http://localhost:5000

Stop Server​

# Find process ID
ps aux | grep serve_docs.py

# Kill process
kill [PID]

# Or kill all Python processes (use with caution!)
pkill -f serve_docs.py

📊 Server Details​

PropertyValue
FrameworkFlask 3.1.2
Port5000
Host0.0.0.0 (all interfaces)
Debug ModeEnabled
Documentation Dir/home/hal/v4/PROJECTS/t2/theia-research/theia_docs_clean
Images Dir/home/hal/v4/PROJECTS/t2/theia-research/theia_docs_clean/images

Dependencies​

flask==3.1.2
markdown==3.9
pygments==2.19.2

All installed in virtual environment: /home/hal/v4/PROJECTS/t2/theia-research/venv/

🎯 Features in Detail​

Markdown Rendering​

  • Parser: python-markdown 3.9
  • Extensions: fenced_code, codehilite, tables, toc, nl2br, sane_lists
  • Syntax Highlighting: Pygments with GitHub theme
  • Code Languages: TypeScript, JavaScript, Python, JSON, YAML, Bash
  • Relative Links: Converted to /view/ URLs
  • Hash Fragments: Preserved (e.g., #section-name)
  • Images: Converted from ../images/ to /images/
  • External Links: Preserved (GitHub, community sites)

UI Components​

  • Header: Dark theme with theia branding
  • Sidebar: Quick links + browsable sections
  • Content: GitHub markdown CSS styling
  • Code Blocks: highlight.js with GitHub theme
  • Frontmatter: Displayed as metadata box

🐛 Troubleshooting​

Server Not Starting​

# Check if port is already in use
netstat -tuln | grep 5000

# Check Python version
python --version  # Should be 3.13+

# Check virtual environment
which python  # Should show venv path
  • Internal .md links should automatically work
  • If broken, check that the file exists in theia_docs_clean/
  • Check server logs for 404 errors

Images Not Loading​

# Verify images directory exists
ls -la /home/hal/v4/PROJECTS/t2/theia-research/theia_docs_clean/images/

# Should show 43 image files

Syntax Highlighting Not Working​

  • Ensure Pygments is installed: pip list | grep pygments
  • Check that code blocks have language tags in markdown
  • Clear browser cache

📝 Development​

Modify Server​

The server code is in: serve_docs.py

Key functions:

  • view_file(filepath) - Renders markdown to HTML
  • convert_md_links() - Converts .md links to /view/ URLs
  • extract_frontmatter() - Parses YAML frontmatter
  • serve_image() - Serves static images

Customize Styling​

Edit the HTML_TEMPLATE in serve_docs.py:

  • Change colors, fonts, layout
  • Modify sidebar links
  • Adjust responsive breakpoints

Add Features​

Ideas for enhancement:

  • Search functionality
  • Table of contents navigation
  • Print-friendly CSS
  • Dark mode toggle
  • Breadcrumb navigation
  • Previous/Next page buttons

✅ Verification​

The server is working correctly if you can:

  • Access http://localhost:5000
  • See the theia homepage with proper styling
  • Navigate using sidebar links
  • Click internal crosslinks (go to other pages)
  • See code blocks with syntax highlighting
  • View images (diagrams, screenshots)
  • Browse /browse/docs and /browse/pages
  • See source URL and crawl timestamp metadata

🎉 Summary​

You now have a fully-functional documentation web server serving the cleaned theia documentation with:

✅ Beautiful GitHub-style UI ✅ Syntax highlighting for 200+ code blocks ✅ 2,585 working internal links ✅ 43 images properly served ✅ Responsive mobile-friendly design ✅ Fast markdown-to-HTML rendering

Perfect for:

  • Local development reference
  • Offline documentation browsing
  • Team knowledge sharing
  • Custom documentation portal

Server Ready! 🚀

Access at: http://localhost:5000 (after port forwarding)