# 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! 📚