graham.systems
Generate web slides from Markdoc
docs(claude): add Claude.md
there he goes
+101
+101
CLAUDE.md
+101
CLAUDE.md
···
1
+
# CLAUDE.md
2
+
3
+
This file provides guidance to Claude Code (claude.ai/code) when working with
4
+
code in this repository.
5
+
6
+
## Development Commands
7
+
8
+
- **Start development server**: `deno task dev` or
9
+
`deno run --unstable-broadcast-channel --allow-env --allow-net --allow-read --allow-write main.ts dev <path-to-markdoc-file>`
10
+
11
+
## Architecture Overview
12
+
13
+
**morkdeck** is a slideshow generator that converts Markdoc files into web-based
14
+
presentations. The architecture follows a modular pipeline with clear separation
15
+
of concerns:
16
+
17
+
### Directory Structure
18
+
19
+
```
20
+
morkdeck/
21
+
├── cli/ # CLI command definitions
22
+
│ └── dev.ts # Dev command interface
23
+
├── core/ # Core rendering logic
24
+
│ ├── markdoc-config.ts # Markdoc configuration
25
+
│ ├── nodes/ # Custom Markdoc nodes
26
+
│ │ └── fence.ts # Code fence with Shiki/Mermaid
27
+
│ └── renderer.ts # Main rendering pipeline
28
+
├── server/ # Development server implementation
29
+
│ └── dev.ts # Live-reload server logic
30
+
├── templates/ # HTML templates
31
+
│ └── live-reload.eta
32
+
└── main.ts # Entry point
33
+
```
34
+
35
+
### Core Components
36
+
37
+
1. **CLI Layer** (`cli/`): Command definitions using Cliffy framework
38
+
- `cli/dev.ts`: Dev command that delegates to server implementation
39
+
40
+
2. **Server Layer** (`server/`): Development server functionality
41
+
- `server/dev.ts`: Live-reload server, file watching, WebSocket handling
42
+
- Serves presentations at port 8000
43
+
- Uses Eta templating engine for HTML generation
44
+
45
+
3. **Core Rendering** (`core/`): Markdoc processing and rendering
46
+
- `core/renderer.ts`: Main rendering pipeline, slide grouping
47
+
- `core/markdoc-config.ts`: Markdoc configuration assembly
48
+
- `core/nodes/fence.ts`: Code fence node with Shiki syntax highlighting and
49
+
Mermaid support
50
+
51
+
### Key Dependencies
52
+
53
+
- **@cliffy/command**: CLI framework
54
+
- **@eta-dev/eta**: Template engine for HTML generation
55
+
- **@markdoc/markdoc**: Markdoc parsing and rendering
56
+
- **shiki**: Syntax highlighting for code blocks
57
+
- **hast-util-is-element**: HAST tree utilities for Shiki integration
58
+
59
+
### Presentation Structure
60
+
61
+
- Each Markdoc file represents a complete presentation
62
+
- Slides are separated by `---` (horizontal rules)
63
+
- The rendering process wraps each slide section in semantic HTML with custom
64
+
tags:
65
+
- `slide` tag → `<section>` element
66
+
- `content` tag → `<div>` element
67
+
- CSS uses container queries and scroll-snap for responsive slide navigation
68
+
69
+
### Code Highlighting Features
70
+
71
+
- **Shiki Integration**: Rose Pine theme syntax highlighting for code blocks
72
+
- **Mermaid Support**: Automatic detection and script injection for Mermaid
73
+
diagrams
74
+
- **Language Detection**: Automatic language detection from fence attributes
75
+
- **HAST Processing**: Converts Shiki HAST output to Markdoc render nodes
76
+
77
+
### Styling Approach
78
+
79
+
The presentation uses a dark theme with centered layout:
80
+
81
+
- Full viewport slides with scroll-snap navigation
82
+
- Container queries for responsive typography
83
+
- Recursive font family with variable font features and monospace code support
84
+
- Rose Pine color scheme (`#191724` background, `#e0def4` headings, `#908caa`
85
+
text)
86
+
87
+
### Live Reload System
88
+
89
+
Uses Deno's BroadcastChannel API to coordinate between:
90
+
91
+
- File watcher that detects changes to the source Markdoc file
92
+
- WebSocket connection that triggers browser reload
93
+
- No external dependencies required for hot reloading
94
+
95
+
### Extending Nodes
96
+
97
+
To add new custom Markdoc nodes:
98
+
99
+
1. Create a new file in `core/nodes/`
100
+
2. Export a function that returns a Markdoc node configuration
101
+
3. Import and add to the `nodes` object in `core/markdoc-config.ts`