graham.systems
+91
-16
CLAUDE.md
+91
-16
CLAUDE.md
···
5
5
6
6
## Development Commands
7
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>`
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/)
10
12
- **Build static presentation**: `deno task build <markdoc-file>` or
11
13
`deno run --allow-env --allow-read --allow-write main.ts build <markdoc-file> --output <directory>`
12
14
···
29
31
│ │ └── fence.ts # Code fence with Shiki/Mermaid
30
32
│ ├── renderer.ts # Main rendering pipeline
31
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
32
41
├── server/ # Development server implementation
33
42
│ └── dev.ts # Live-reload server logic
34
43
├── templates/ # Eta templates
35
44
│ ├── presentation.eta # Main template
45
+
│ ├── components/ # Component templates
46
+
│ │ ├── presentation.eta # Inline Lit presentation component
47
+
│ │ └── slide.eta # Inline Lit slide component
36
48
│ └── partials/ # Template partials
37
49
│ ├── live-reload.eta # Live-reload scripts
38
50
│ ├── mermaid.eta # Mermaid initialization
39
51
│ └── slide-styles.eta # CSS styles
52
+
├── dist/ # Built runtime assets
40
53
└── main.ts # Entry point
41
54
```
42
55
···
46
59
- `cli/dev.ts`: Dev command that delegates to server implementation
47
60
- `cli/build.ts`: Build command for static HTML generation
48
61
49
-
2. **Server Layer** (`server/`): Development server functionality
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
50
76
- `server/dev.ts`: Live-reload server, file watching, WebSocket handling
51
77
- Serves presentations at port 8000
52
78
- Uses consolidated template system
53
79
54
-
3. **Core Rendering** (`core/`): Markdoc processing and rendering
55
-
- `core/renderer.ts`: Unified rendering pipeline with `renderPresentationHtml()`
80
+
5. **Core Rendering** (`core/`): Markdoc processing and rendering
81
+
- `core/renderer.ts`: Unified rendering pipeline with
82
+
`renderPresentationHtml()`
56
83
- `core/markdoc-config.ts`: Markdoc configuration with includes tracking
57
-
- `core/nodes/fence.ts`: Code fence node with Shiki syntax highlighting and Mermaid support
84
+
- `core/nodes/fence.ts`: Code fence node with Shiki syntax highlighting and
85
+
Mermaid support
58
86
- `core/types.ts`: Type definitions for render options and includes
59
87
60
88
### Key Dependencies
···
64
92
- **@markdoc/markdoc**: Markdoc parsing and rendering
65
93
- **shiki**: Syntax highlighting for code blocks
66
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
67
98
68
99
### Template System
69
100
70
-
**Consolidated Template Architecture:**
101
+
**Hybrid Template Architecture:**
102
+
71
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
72
108
- **`templates/partials/`**: Modular template components
109
+
- `importmap.eta`: Import map for Lit CDN dependencies
73
110
- `live-reload.eta`: WebSocket live-reload functionality (dev only)
74
111
- `mermaid.eta`: Mermaid diagram initialization scripts
75
112
- `slide-styles.eta`: CSS styling for presentations
76
113
77
114
**Template Features:**
115
+
78
116
- **Includes System**: Dynamic script/style injection based on content needs
79
117
- **Mode Detection**: Automatic dev vs static build differentiation
80
118
- **Partial Composition**: Modular template components for maintainability
···
83
121
84
122
- Each Markdoc file represents a complete presentation
85
123
- 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
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
90
130
91
131
### Code Highlighting Features
92
132
93
133
- **Shiki Integration**: Rose Pine theme syntax highlighting for code blocks
94
-
- **Mermaid Support**: Automatic detection and script injection for Mermaid diagrams
134
+
- **Mermaid Support**: Automatic detection and script injection for Mermaid
135
+
diagrams
95
136
- **Language Detection**: Automatic language detection from fence attributes
96
137
- **HAST Processing**: Converts Shiki HAST output to Markdoc render nodes
97
138
98
139
### Build System
99
140
100
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
101
146
- Live-reload server at port 8000
102
-
- File watching with automatic rebuild
103
147
- WebSocket-based browser refresh
104
148
- No cache headers for development
105
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
+
106
159
**Static Build (`deno task build`):**
107
-
- Single HTML file output
160
+
161
+
- Single HTML file output with embedded runtime
108
162
- No live-reload dependencies
109
163
- Optimized for deployment
110
164
- Custom output directory support
···
112
166
### Styling Approach
113
167
114
168
The presentation uses a dark theme with centered layout:
115
-
- Full viewport slides with scroll-snap navigation
169
+
170
+
- Full viewport slides with scroll-snap navigation via Lit component CSS
116
171
- Container queries for responsive typography
117
172
- Recursive font family with variable font features and monospace code support
118
-
- Rose Pine color scheme (`#191724` background, `#e0def4` headings, `#908caa` text)
173
+
- Rose Pine color scheme (`#191724` background, `#e0def4` headings, `#908caa`
174
+
text)
175
+
- Shadow DOM styling in Lit components with :host selectors
119
176
120
177
### Extending the System
121
178
122
179
**Adding Custom Markdoc Nodes:**
180
+
123
181
1. Create a new file in `core/nodes/`
124
182
2. Export a function that returns a Markdoc node configuration
125
183
3. Import and add to the `nodes` object in `core/markdoc-config.ts`
126
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
+
127
191
**Adding Template Partials:**
192
+
128
193
1. Create new `.eta` files in `templates/partials/`
129
194
2. Use includes system to conditionally load based on content needs
130
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