this repo has no description
docs(claude): update Claude.md
+58
-29
+58
-29
CLAUDE.md
+58
-29
CLAUDE.md
···
5
5
6
6
## Development Commands
7
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>`
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>`
10
12
11
13
## Architecture Overview
12
14
···
19
21
```
20
22
morkdeck/
21
23
├── cli/ # CLI command definitions
22
-
│ └── dev.ts # Dev command interface
24
+
│ ├── dev.ts # Dev command interface
25
+
│ └── build.ts # Build command interface
23
26
├── core/ # Core rendering logic
24
27
│ ├── markdoc-config.ts # Markdoc configuration
25
28
│ ├── nodes/ # Custom Markdoc nodes
26
29
│ │ └── fence.ts # Code fence with Shiki/Mermaid
27
-
│ └── renderer.ts # Main rendering pipeline
30
+
│ ├── renderer.ts # Main rendering pipeline
31
+
│ └── types.ts # TypeScript type definitions
28
32
├── server/ # Development server implementation
29
33
│ └── dev.ts # Live-reload server logic
30
-
├── templates/ # HTML templates
31
-
│ └── live-reload.eta
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
32
40
└── main.ts # Entry point
33
41
```
34
42
···
36
44
37
45
1. **CLI Layer** (`cli/`): Command definitions using Cliffy framework
38
46
- `cli/dev.ts`: Dev command that delegates to server implementation
47
+
- `cli/build.ts`: Build command for static HTML generation
39
48
40
49
2. **Server Layer** (`server/`): Development server functionality
41
50
- `server/dev.ts`: Live-reload server, file watching, WebSocket handling
42
51
- Serves presentations at port 8000
43
-
- Uses Eta templating engine for HTML generation
52
+
- Uses consolidated template system
44
53
45
54
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
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
50
59
51
60
### Key Dependencies
52
61
···
56
65
- **shiki**: Syntax highlighting for code blocks
57
66
- **hast-util-is-element**: HAST tree utilities for Shiki integration
58
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
81
+
59
82
### Presentation Structure
60
83
61
84
- Each Markdoc file represents a complete presentation
62
85
- Slides are separated by `---` (horizontal rules)
63
-
- The rendering process wraps each slide section in semantic HTML with custom
64
-
tags:
86
+
- The rendering process wraps each slide section in semantic HTML with custom tags:
65
87
- `slide` tag → `<section>` element
66
88
- `content` tag → `<div>` element
67
89
- CSS uses container queries and scroll-snap for responsive slide navigation
···
69
91
### Code Highlighting Features
70
92
71
93
- **Shiki Integration**: Rose Pine theme syntax highlighting for code blocks
72
-
- **Mermaid Support**: Automatic detection and script injection for Mermaid
73
-
diagrams
94
+
- **Mermaid Support**: Automatic detection and script injection for Mermaid diagrams
74
95
- **Language Detection**: Automatic language detection from fence attributes
75
96
- **HAST Processing**: Converts Shiki HAST output to Markdoc render nodes
76
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
111
+
77
112
### Styling Approach
78
113
79
114
The presentation uses a dark theme with centered layout:
80
-
81
115
- Full viewport slides with scroll-snap navigation
82
116
- Container queries for responsive typography
83
117
- Recursive font family with variable font features and monospace code support
84
-
- Rose Pine color scheme (`#191724` background, `#e0def4` headings, `#908caa`
85
-
text)
118
+
- Rose Pine color scheme (`#191724` background, `#e0def4` headings, `#908caa` text)
86
119
87
-
### Live Reload System
120
+
### Extending the System
88
121
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
-
122
+
**Adding Custom Markdoc Nodes:**
99
123
1. Create a new file in `core/nodes/`
100
124
2. Export a function that returns a Markdoc node configuration
101
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