254 lines
7.4 KiB
Markdown
254 lines
7.4 KiB
Markdown
# 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):
|
|
```bash
|
|
# 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:
|
|
|
|
```javascript
|
|
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`:
|
|
|
|
```javascript
|
|
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! 📚
|