SmartCane/webapps/markdown_docs_viewer/README.md

SmartCane Documentation Viewer

A lightweight, browser-based markdown documentation viewer for SmartCane architecture guides and system documentation.

Features

✨ Simple Single-Page App

• No backend required
• Static HTML/JS/CSS
• Works on any static hosting (Netlify, GitHub Pages, etc.)
• Perfect for local development or production

📚 Dynamic Document Loading

• Sidebar auto-populates from markdown files in ../docs/
• Click to view any documentation file
• Search/filter documents by name

🎨 Beautiful Rendering

• Inherited SmartCane branding (teal/blue theme from ../theme.css)
• Responsive design (desktop, tablet, mobile)
• Properly styled markdown elements:
  • Headings with hierarchy
  • Code blocks with background highlighting
  • Tables with alternating rows
  • Blockquotes and lists
  • Links with hover effects

🔒 Security

• All HTML output is sanitized with DOMPurify
• Prevents XSS injection from markdown content
• Safe for user-uploaded or external documentation

🔗 Bookmarkable & Shareable

• URL hash tracks current document (e.g., #ARCHITECTURE_DATA_FLOW)
• Reload page or share link with hash to jump directly to document
• Browser back/forward work as expected

File Structure

webapps/markdown_docs_viewer/
├── index.html                # Main page (layout + header)
├── script.js                 # Markdown loading logic
├── style.css                 # Custom styles + layout
├── lib/                      # (Optional local library storage)
└── README.md                 # This file

Setup

Prerequisites

• No installation required—pure HTML/CSS/JavaScript
• External libraries loaded via CDN:
  • marked.js (v11.1.0) — Markdown parser
  • DOMPurify.js (v3.0.0) — HTML sanitizer

Local Development

1. Place markdown files in ../docs/ folder (same level as ../webapps/)

   SmartCane_code/
   ├── webapps/
   │   ├── markdown_docs_viewer/
   │   │   ├── index.html
   │   │   ├── script.js
   │   │   └── style.css
   │   └── docs/              ← Markdown files go here
   │       ├── system_architecture.md
   │       ├── ARCHITECTURE_DATA_FLOW.md
   │       └── ...
   

2. Open index.html in a browser (or use a local HTTP server):

   # Python 3
   python -m http.server 8000
   
   # Then visit: http://localhost:8000/webapps/markdown_docs_viewer/
   

3. Click documents in the sidebar to view them

Deployment to Netlify

1. Ensure system_architecture/ folder is moved to webapps/docs/:

   webapps/
   ├── markdown_docs_viewer/    ← The viewer app
   └── docs/                    ← All .md files here
   

2. Push to GitHub (the code-improvements branch)

3. Netlify will auto-deploy the entire webapps/ folder

4. Access at: https://your-site.netlify.app/markdown_docs_viewer/

How It Works

Page Load Flow

1. User opens index.html
   ↓
2. JavaScript executes `populateDocumentList()`
   ├─ Fetches list of .md files from ../docs/
   ├─ Sorts alphabetically (system_architecture.md first)
   └─ Creates clickable links in sidebar
   ↓
3. Check URL hash:
   ├─ If hash exists (e.g., #ARCHITECTURE_DATA_FLOW)
   │  └─ Load that document automatically
   └─ If no hash, show welcome message
   ↓
4. Setup complete—user can click docs to load

Document Loading

1. User clicks a document link
   ↓
2. `loadDocument(docId)` is called
   ├─ Fetches markdown file: fetch('../docs/{docId}.md')
   ├─ Parses with marked.js: marked.parse(markdown)
   ├─ Sanitizes with DOMPurify.sanitize(html)
   ├─ Insert into #content div
   └─ Update URL hash for bookmarking
   ↓
3. Markdown is rendered with custom CSS styling

Customization

Adding New Documents

Simply add .md files to webapps/docs/ folder. They'll automatically appear in the sidebar on next page load.

Changing Document Order

Edit the docFiles array in script.js populateDocumentList() function:

const docFiles = [
    'system_architecture.md',          // Always first
    'ARCHITECTURE_DATA_FLOW.md',
    // ... add more
];

Changing Display Names

Update the nameMap in formatDocName() function in script.js:

const nameMap = {
    'system_architecture.md': '🏗️ System Architecture',  // Change the emoji or text
    'YOUR_FILE.md': '🎯 Your Custom Name',
    // ...
};

Styling Adjustments

• Colors: Modify CSS variables at top of style.css (:root section)

  • --smartcane-teal: Main color
  • --smartcane-dark: Darker accent
  • --accent-color: Link color

• Layout: Change sidebar width (default 280px) or adjust breakpoints in media queries

• Fonts: Update font-family in body rule

Browser Support

• ✅ Chrome 90+
• ✅ Firefox 88+
• ✅ Safari 14+
• ✅ Edge 90+
• ⚠️ IE 11: Not supported (uses modern ES6+ features)

Troubleshooting

Documents not loading?

1. Check folder path: Ensure ../docs/ folder exists relative to index.html
2. Check filenames: File names are case-sensitive (e.g., ARCHITECTURE_DATA_FLOW.md ≠ architecture_data_flow.md)
3. CORS error: If running locally via file:// protocol, use a local HTTP server instead
4. Browser console: Open DevTools (F12) and check Console tab for error messages

Styling looks different?

• Ensure ../theme.css exists (inherited for SmartCane branding)
• Check that style.css is loaded (should see in Network tab)
• Clear browser cache (Ctrl+Shift+Delete) and reload

Search not working?

• Search filters sidebar document list (case-insensitive)
• Only shows documents matching the search term
• Clear search input to see all documents again

Technical Notes

Performance

• Fast rendering: marked.js renders ~1MB markdown in <100ms
• Minimal dependencies: Only 2 external libraries (58KB total gzipped)
• No build step needed: Pure HTML/CSS/JS, no transpilation required
• Caching: Browser caches .md files and libraries automatically

Security

• DOMPurify sanitization: Removes any <script> tags or event handlers from markdown output
• No eval(): JavaScript never executes dynamic code
• No database: Files read-only; no server-side connections

Accessibility

• Semantic HTML with proper heading hierarchy
• ARIA labels on interactive elements
• Keyboard navigation (Tab to move between links)
• Good color contrast (WCAG AA compliant)

Future Enhancements

Optional features that parents can add later:

• Full-text search across all documents (with Lunr.js)
• Table of contents auto-generation from heading hierarchy
• Dark mode toggle
• Print stylesheet for Word/PDF export
• Copy code blocks to clipboard button
• GitHub edit links (with "Edit on GitHub" button)
• Revision history from git
• Multi-language support

Dependencies

Library	Version	Source	Purpose
marked.js	11.1.0	CDN	Parse markdown to HTML
DOMPurify.js	3.0.0	CDN	Sanitize HTML output

Both are loaded from jsdelivr.com CDN automatically—no local installation needed.

License

SmartCane internal documentation viewer. Used for system architecture & developer guides.

Support

Questions or issues? Check the documentation files themselves—they're the source of truth for system architecture! 📚