this repo has no description
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with
4code in this repository.
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
15## Architecture Overview
16
17**morkdeck** is a slideshow generator that converts Markdoc files into web-based
18presentations. The architecture follows a modular pipeline with clear separation
19of concerns:
20
21### Directory Structure
22
23```
24morkdeck/
25├── cli/ # CLI command definitions
26│ ├── dev.ts # Dev command interface
27│ └── build.ts # Build command interface
28├── core/ # Core rendering logic
29│ ├── markdoc-config.ts # Markdoc configuration
30│ ├── nodes/ # Custom Markdoc nodes
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
56### Core Components
57
581. **CLI Layer** (`cli/`): Command definitions using Cliffy framework
59 - `cli/dev.ts`: Dev command that delegates to server implementation
60 - `cli/build.ts`: Build command for static HTML generation
61
622. **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
693. **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
754. **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
805. **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
89
90- **@cliffy/command**: CLI framework
91- **@eta-dev/eta**: Template engine for HTML generation
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
119
120### Presentation Structure
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
165
166### Styling Approach
167
168The 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
1811. Create a new file in `core/nodes/`
1822. Export a function that returns a Markdoc node configuration
1833. Import and add to the `nodes` object in `core/markdoc-config.ts`
184
185**Adding Runtime Components:**
186
1871. Create new Lit components in `runtime/components/`
1882. Register custom elements in `runtime/morkdeck.ts`
1893. Add corresponding template components in `templates/components/` if needed
190
191**Adding Template Partials:**
192
1931. Create new `.eta` files in `templates/partials/`
1942. Use includes system to conditionally load based on content needs
1953. 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
200experience with:
201
202- Automatic runtime bundling and rebuilding
203- Core server restart on backend changes
204- Live browser reload
205- Port 8000 presentation serving