### Implementation Approach (GitHub)
GitHub uses a two-stage rendering process: an HTML pipeline identifies `mermaid` code blocks, then an iframe with their Viewscreen service renders diagrams asynchronously. This isolates user content and reduces JavaScript payload.
### Progressive Enhancement
Clients without JavaScript see the original markdown code, ensuring content remains accessible.
### Math (KaTeX vs MathJax)
| Library | Pros | Cons |
|---------|------|------|
| **KaTeX** | Fastest rendering, no reflow, self-contained | Smaller feature set |
| **MathJax** | Most complete LaTeX support, accessibility features | Heavier, slower |
- Inline: `$E = mc^2$` or `\(E = mc^2\)`
- Block: `$$\int_0^\infty e^{-x^2} dx$$` or `\[...\]`
### Callouts/Admonitions (fragmented landscape)
| **GitHub** | `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, `> [!IMPORTANT]`, `> [!CAUTION]` |
| **MyST** | `:::{note}`, `:::{tip}`, `:::{warning}` with directive syntax |
| **MkDocs Material** | `!!! note "Title"` with indented content |
| **Obsidian** | `> [!info]`, `> [!warning]` (similar to GitHub) |
GitHub's syntax is gaining adoption as the emerging standard due to GitHub's influence. It builds on blockquote syntax which degrades gracefully.
- Images: Standard `` with optional sizing
- Videos: Platform-specific or HTML `<video>` tags
- iframes: Generally require HTML or MDX
- Foreign media: No standardized markdown syntax yet
| Aspect | Markdown | MDX |
|--------|----------|-----|
| **Learning curve** | Very low | Medium-high (requires React/JSX) |
| **Interactivity** | Static only | Full React components |
| **Performance** | Fast, no overhead | Slightly heavier (React bundle) |
| **Collaboration** | Easy for non-developers | Technical writers need JSX knowledge |
| **Use cases** | Docs, READMEs, blogs, notes | Interactive tutorials, component docs |
| **Framework support** | Universal | Next.js, Gatsby, Remix (React ecosystem) |
- Interactive code playgrounds
- Embedded data visualizations
- Component documentation with live examples
- Dynamic content based on state
### When to stick with Markdown
- Cross-platform compatibility
## Live Preview and Editing Approaches
### 1. Split-Pane (Traditional)
- Editor on left, rendered preview on right
- Examples: VS Code, many web editors
- Pros: Full control over raw markdown, familiar
- Cons: Context switching, screen real estate
### 2. WYSIWYG / "What You See Is What You Mean"
- Renders markdown inline as you type
- Example: Typora (renders in place)
- Pros: Intuitive, focused writing experience
- Cons: Harder to see/edit raw syntax
### 3. Hybrid/Block-Based
- Blocks render but allow raw editing on focus
- Examples: Notion-style editors, Obsidian (partially)
- Pros: Best of both worlds
- Cons: More complex interaction model
- AI-assisted writing integration (ShyEditor, others)
- Real-time collaboration (Google Docs-style)
- Minimal/distraction-free modes
- Mobile-first responsive editing
## CommonMark Extensions Landscape
### Deployed Extensions (widely implemented)
### Proposed Extensions (under discussion)
- Attributes (generic `{#id .class}` syntax)
The CommonMark spec deliberately stays minimal, with extensions handled by individual implementations. GFM has become the practical extended standard.
## Key Takeaways for Implementation
1. **Start with GFM compatibility** - it's the baseline expectation
2. **Add Mermaid support** - increasingly expected, especially for technical docs
3. **Support GitHub-style alerts** - emerging as the admonition standard
4. **Include math rendering** - KaTeX for speed, MathJax for completeness
5. **Provide flexible preview** - at minimum split-pane, ideally hybrid
6. **Consider MDX** - but only if your audience is technical and React-familiar
7. **Export options matter** - PDF, HTML, and ideally DOCX
8. **AI integration** - becoming a differentiator in 2025