graham.systems
Generate web slides from Markdoc
docs(claude): update CLAUDE.md
+91
-16
+91
-16
CLAUDE.md
+91
-16
CLAUDE.md
···
5
6
## Development Commands
7
8
-
- **Start development server**: `deno task dev <markdoc-file>` or
9
-
`deno run --unstable-broadcast-channel --allow-env --allow-net --allow-read --allow-write main.ts dev <markdoc-file>`
10
- **Build static presentation**: `deno task build <markdoc-file>` or
11
`deno run --allow-env --allow-read --allow-write main.ts build <markdoc-file> --output <directory>`
12
···
29
│ │ └── fence.ts # Code fence with Shiki/Mermaid
30
│ ├── renderer.ts # Main rendering pipeline
31
│ └── types.ts # TypeScript type definitions
32
├── server/ # Development server implementation
33
│ └── dev.ts # Live-reload server logic
34
├── templates/ # Eta templates
35
│ ├── presentation.eta # Main template
36
│ └── partials/ # Template partials
37
│ ├── live-reload.eta # Live-reload scripts
38
│ ├── mermaid.eta # Mermaid initialization
39
│ └── slide-styles.eta # CSS styles
40
└── main.ts # Entry point
41
```
42
···
46
- `cli/dev.ts`: Dev command that delegates to server implementation
47
- `cli/build.ts`: Build command for static HTML generation
48
49
-
2. **Server Layer** (`server/`): Development server functionality
50
- `server/dev.ts`: Live-reload server, file watching, WebSocket handling
51
- Serves presentations at port 8000
52
- Uses consolidated template system
53
54
-
3. **Core Rendering** (`core/`): Markdoc processing and rendering
55
-
- `core/renderer.ts`: Unified rendering pipeline with `renderPresentationHtml()`
56
- `core/markdoc-config.ts`: Markdoc configuration with includes tracking
57
-
- `core/nodes/fence.ts`: Code fence node with Shiki syntax highlighting and Mermaid support
58
- `core/types.ts`: Type definitions for render options and includes
59
60
### Key Dependencies
···
64
- **@markdoc/markdoc**: Markdoc parsing and rendering
65
- **shiki**: Syntax highlighting for code blocks
66
- **hast-util-is-element**: HAST tree utilities for Shiki integration
67
68
### Template System
69
70
-
**Consolidated Template Architecture:**
71
- **`templates/presentation.eta`**: Main template for both dev and static builds
72
- **`templates/partials/`**: Modular template components
73
- `live-reload.eta`: WebSocket live-reload functionality (dev only)
74
- `mermaid.eta`: Mermaid diagram initialization scripts
75
- `slide-styles.eta`: CSS styling for presentations
76
77
**Template Features:**
78
- **Includes System**: Dynamic script/style injection based on content needs
79
- **Mode Detection**: Automatic dev vs static build differentiation
80
- **Partial Composition**: Modular template components for maintainability
···
83
84
- Each Markdoc file represents a complete presentation
85
- Slides are separated by `---` (horizontal rules)
86
-
- The rendering process wraps each slide section in semantic HTML with custom tags:
87
-
- `slide` tag → `<section>` element
88
-
- `content` tag → `<div>` element
89
-
- CSS uses container queries and scroll-snap for responsive slide navigation
90
91
### Code Highlighting Features
92
93
- **Shiki Integration**: Rose Pine theme syntax highlighting for code blocks
94
-
- **Mermaid Support**: Automatic detection and script injection for Mermaid diagrams
95
- **Language Detection**: Automatic language detection from fence attributes
96
- **HAST Processing**: Converts Shiki HAST output to Markdoc render nodes
97
98
### Build System
99
100
**Development Mode (`deno task dev`):**
101
- Live-reload server at port 8000
102
-
- File watching with automatic rebuild
103
- WebSocket-based browser refresh
104
- No cache headers for development
105
106
**Static Build (`deno task build`):**
107
-
- Single HTML file output
108
- No live-reload dependencies
109
- Optimized for deployment
110
- Custom output directory support
···
112
### Styling Approach
113
114
The presentation uses a dark theme with centered layout:
115
-
- Full viewport slides with scroll-snap navigation
116
- Container queries for responsive typography
117
- Recursive font family with variable font features and monospace code support
118
-
- Rose Pine color scheme (`#191724` background, `#e0def4` headings, `#908caa` text)
119
120
### Extending the System
121
122
**Adding Custom Markdoc Nodes:**
123
1. Create a new file in `core/nodes/`
124
2. Export a function that returns a Markdoc node configuration
125
3. Import and add to the `nodes` object in `core/markdoc-config.ts`
126
127
**Adding Template Partials:**
128
1. Create new `.eta` files in `templates/partials/`
129
2. Use includes system to conditionally load based on content needs
130
3. Update `core/markdoc-config.ts` to track new includes
···
5
6
## Development Commands
7
8
+
- **Start development server**: `deno task dev` (uses scripts/dev.ts with
9
+
runtime bundling and file watching)
10
+
- **Core development server**: `deno task dev:core` (direct main.ts dev command)
11
+
- **Runtime development**: `deno task dev:runtime` (bundles runtime to dist/)
12
- **Build static presentation**: `deno task build <markdoc-file>` or
13
`deno run --allow-env --allow-read --allow-write main.ts build <markdoc-file> --output <directory>`
14
···
31
│ │ └── fence.ts # Code fence with Shiki/Mermaid
32
│ ├── renderer.ts # Main rendering pipeline
33
│ └── types.ts # TypeScript type definitions
34
+
├── runtime/ # Client-side runtime components
35
+
│ ├── components/ # Lit-based web components
36
+
│ │ ├── presentation.ts # Presentation component
37
+
│ │ └── slide.ts # Slide component
38
+
│ └── morkdeck.ts # Runtime entry point
39
+
├── scripts/ # Development scripts
40
+
│ └── dev.ts # Enhanced dev command with esbuild
41
├── server/ # Development server implementation
42
│ └── dev.ts # Live-reload server logic
43
├── templates/ # Eta templates
44
│ ├── presentation.eta # Main template
45
+
│ ├── components/ # Component templates
46
+
│ │ ├── presentation.eta # Inline Lit presentation component
47
+
│ │ └── slide.eta # Inline Lit slide component
48
│ └── partials/ # Template partials
49
│ ├── live-reload.eta # Live-reload scripts
50
│ ├── mermaid.eta # Mermaid initialization
51
│ └── slide-styles.eta # CSS styles
52
+
├── dist/ # Built runtime assets
53
└── main.ts # Entry point
54
```
55
···
59
- `cli/dev.ts`: Dev command that delegates to server implementation
60
- `cli/build.ts`: Build command for static HTML generation
61
62
+
2. **Runtime Layer** (`runtime/`): Client-side web components using Lit
63
+
- `runtime/components/presentation.ts`: Presentation container with
64
+
scroll-snap and URL sync
65
+
- `runtime/components/slide.ts`: Individual slide component
66
+
- `runtime/morkdeck.ts`: Custom element registration entry point
67
+
- Built to `dist/morkdeck.js` via esbuild
68
+
69
+
3. **Scripts Layer** (`scripts/`): Enhanced development tooling
70
+
- `scripts/dev.ts`: Orchestrates both runtime bundling and core server with
71
+
file watching
72
+
- Watches runtime files and rebuilds with esbuild
73
+
- Watches core files and restarts development server
74
+
75
+
4. **Server Layer** (`server/`): Development server functionality
76
- `server/dev.ts`: Live-reload server, file watching, WebSocket handling
77
- Serves presentations at port 8000
78
- Uses consolidated template system
79
80
+
5. **Core Rendering** (`core/`): Markdoc processing and rendering
81
+
- `core/renderer.ts`: Unified rendering pipeline with
82
+
`renderPresentationHtml()`
83
- `core/markdoc-config.ts`: Markdoc configuration with includes tracking
84
+
- `core/nodes/fence.ts`: Code fence node with Shiki syntax highlighting and
85
+
Mermaid support
86
- `core/types.ts`: Type definitions for render options and includes
87
88
### Key Dependencies
···
92
- **@markdoc/markdoc**: Markdoc parsing and rendering
93
- **shiki**: Syntax highlighting for code blocks
94
- **hast-util-is-element**: HAST tree utilities for Shiki integration
95
+
- **lit**: Web component library for runtime components
96
+
- **esbuild**: Runtime bundling and TypeScript compilation
97
+
- **@deno/esbuild-plugin**: Deno module resolution for esbuild
98
99
### Template System
100
101
+
**Hybrid Template Architecture:**
102
+
103
- **`templates/presentation.eta`**: Main template for both dev and static builds
104
+
- **`templates/components/`**: Inline Lit component templates
105
+
- `presentation.eta`: Inline Lit Presentation component with
106
+
IntersectionObserver
107
+
- `slide.eta`: Inline Lit Slide component
108
- **`templates/partials/`**: Modular template components
109
+
- `importmap.eta`: Import map for Lit CDN dependencies
110
- `live-reload.eta`: WebSocket live-reload functionality (dev only)
111
- `mermaid.eta`: Mermaid diagram initialization scripts
112
- `slide-styles.eta`: CSS styling for presentations
113
114
**Template Features:**
115
+
116
- **Includes System**: Dynamic script/style injection based on content needs
117
- **Mode Detection**: Automatic dev vs static build differentiation
118
- **Partial Composition**: Modular template components for maintainability
···
121
122
- Each Markdoc file represents a complete presentation
123
- Slides are separated by `---` (horizontal rules)
124
+
- The rendering process wraps each slide section in semantic HTML with custom
125
+
web components:
126
+
- `morkdeck-presentation` → Lit-based presentation container
127
+
- `morkdeck-slide` → Lit-based individual slide wrapper
128
+
- Presentation component handles scroll-snap navigation and URL synchronization
129
+
- IntersectionObserver tracks visible slides and updates browser URL hash
130
131
### Code Highlighting Features
132
133
- **Shiki Integration**: Rose Pine theme syntax highlighting for code blocks
134
+
- **Mermaid Support**: Automatic detection and script injection for Mermaid
135
+
diagrams
136
- **Language Detection**: Automatic language detection from fence attributes
137
- **HAST Processing**: Converts Shiki HAST output to Markdoc render nodes
138
139
### Build System
140
141
**Development Mode (`deno task dev`):**
142
+
143
+
- Enhanced development workflow via `scripts/dev.ts`
144
+
- Runtime bundling with esbuild watching `runtime/` directory
145
+
- Core server restart when `core/`, `server/`, or `cli/` files change
146
- Live-reload server at port 8000
147
- WebSocket-based browser refresh
148
- No cache headers for development
149
150
+
**Core Development Mode (`deno task dev:core`):**
151
+
152
+
- Direct main.ts dev command execution
153
+
- Basic file watching without runtime bundling
154
+
155
+
**Runtime Development (`deno task dev:runtime`):**
156
+
157
+
- Standalone runtime bundling to `dist/morkdeck.js`
158
+
159
**Static Build (`deno task build`):**
160
+
161
+
- Single HTML file output with embedded runtime
162
- No live-reload dependencies
163
- Optimized for deployment
164
- Custom output directory support
···
166
### Styling Approach
167
168
The presentation uses a dark theme with centered layout:
169
+
170
+
- Full viewport slides with scroll-snap navigation via Lit component CSS
171
- Container queries for responsive typography
172
- Recursive font family with variable font features and monospace code support
173
+
- Rose Pine color scheme (`#191724` background, `#e0def4` headings, `#908caa`
174
+
text)
175
+
- Shadow DOM styling in Lit components with :host selectors
176
177
### Extending the System
178
179
**Adding Custom Markdoc Nodes:**
180
+
181
1. Create a new file in `core/nodes/`
182
2. Export a function that returns a Markdoc node configuration
183
3. Import and add to the `nodes` object in `core/markdoc-config.ts`
184
185
+
**Adding Runtime Components:**
186
+
187
+
1. Create new Lit components in `runtime/components/`
188
+
2. Register custom elements in `runtime/morkdeck.ts`
189
+
3. Add corresponding template components in `templates/components/` if needed
190
+
191
**Adding Template Partials:**
192
+
193
1. Create new `.eta` files in `templates/partials/`
194
2. Use includes system to conditionally load based on content needs
195
3. Update `core/markdoc-config.ts` to track new includes
196
+
197
+
### Development Workflow
198
+
199
+
**Primary Development Command**: Use `deno task dev` for the full development
200
+
experience with:
201
+
202
+
- Automatic runtime bundling and rebuilding
203
+
- Core server restart on backend changes
204
+
- Live browser reload
205
+
- Port 8000 presentation serving