@entropicwarrior/sdoc 0.1.17 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/reference/sdoc-authoring.sdoc +110 -6
- package/lexica/specification.sdoc +185 -27
- package/package.json +1 -1
- package/src/notion-renderer.js +3 -0
- package/src/sdoc.js +213 -129
- package/src/slide-renderer.js +21 -6
- package/docs/guide/intro.sdoc +0 -112
- package/docs/guide/notion-sync.sdoc +0 -177
- package/docs/guide/setup.sdoc +0 -112
- package/docs/guide/why-sdoc.sdoc +0 -206
- package/docs/index.sdoc +0 -39
- package/docs/reference/api.sdoc +0 -208
- package/docs/reference/cli.sdoc +0 -188
- package/docs/reference/syntax.sdoc +0 -502
- package/docs/tutorials/first-steps.sdoc +0 -117
package/docs/reference/api.sdoc
DELETED
|
@@ -1,208 +0,0 @@
|
|
|
1
|
-
# JavaScript API Reference
|
|
2
|
-
{
|
|
3
|
-
@meta {
|
|
4
|
-
sdoc-version: 0.1
|
|
5
|
-
}
|
|
6
|
-
|
|
7
|
-
The SDOC parser and renderer are in `src/sdoc.js`. All functions are exported via CommonJS. The package is available on npm as `@entropicwarrior/sdoc`.
|
|
8
|
-
|
|
9
|
-
# Installation
|
|
10
|
-
{
|
|
11
|
-
```bash
|
|
12
|
-
npm install @entropicwarrior/sdoc
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
Subpath exports are available for individual renderers:
|
|
16
|
-
|
|
17
|
-
```javascript
|
|
18
|
-
const { parseSdoc, extractMeta } = require("@entropicwarrior/sdoc");
|
|
19
|
-
const { renderNotionBlocks } = require("@entropicwarrior/sdoc/notion");
|
|
20
|
-
const { renderSlides } = require("@entropicwarrior/sdoc/slides");
|
|
21
|
-
const { exportSlidePdf, exportDocPdf } = require("@entropicwarrior/sdoc/slide-pdf");
|
|
22
|
-
const { knowledgeDir } = require("@entropicwarrior/sdoc/knowledge");
|
|
23
|
-
```
|
|
24
|
-
}
|
|
25
|
-
|
|
26
|
-
# parseSdoc(text)
|
|
27
|
-
{
|
|
28
|
-
Parses an SDOC string into an AST.
|
|
29
|
-
|
|
30
|
-
```javascript
|
|
31
|
-
const { parseSdoc } = require("@entropicwarrior/sdoc");
|
|
32
|
-
const { nodes, errors } = parseSdoc(sdocText);
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
{[.]
|
|
36
|
-
- `text` -- the SDOC source string
|
|
37
|
-
- Returns `{ nodes, errors }` where `nodes` is an array of AST nodes and `errors` is an array of `{ message, line }` objects
|
|
38
|
-
}
|
|
39
|
-
}
|
|
40
|
-
|
|
41
|
-
# extractMeta(nodes)
|
|
42
|
-
{
|
|
43
|
-
Extracts the `@meta` scope from parsed nodes and returns the remaining body nodes.
|
|
44
|
-
|
|
45
|
-
```javascript
|
|
46
|
-
const { parseSdoc, extractMeta } = require("@entropicwarrior/sdoc");
|
|
47
|
-
const parsed = parseSdoc(text);
|
|
48
|
-
const { nodes, meta } = extractMeta(parsed.nodes);
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
{[.]
|
|
52
|
-
- `nodes` -- the AST node array from `parseSdoc`
|
|
53
|
-
- Returns `{ nodes, meta }` where `meta` contains `stylePath`, `styleAppendPath`, `headerNodes`, `footerNodes`, `headerText`, `footerText`, and `properties`
|
|
54
|
-
- `headerText` and `footerText` are set by key:value meta syntax (e.g., `header: My Header`)
|
|
55
|
-
- `properties` is an object of arbitrary key:value pairs from the meta scope (e.g., `author`, `date`, `version`)
|
|
56
|
-
}
|
|
57
|
-
}
|
|
58
|
-
|
|
59
|
-
# renderHtmlDocument(text, title, options)
|
|
60
|
-
{
|
|
61
|
-
Parses and renders a complete HTML page from SDOC source.
|
|
62
|
-
|
|
63
|
-
```javascript
|
|
64
|
-
const { renderHtmlDocument } = require("@entropicwarrior/sdoc");
|
|
65
|
-
const html = renderHtmlDocument(sdocText, "Page Title", {
|
|
66
|
-
config: { header: "My Header", footer: "My Footer" },
|
|
67
|
-
cssOverride: customCssString,
|
|
68
|
-
cssAppend: additionalCssString
|
|
69
|
-
});
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
{[.]
|
|
73
|
-
- `text` -- SDOC source string
|
|
74
|
-
- `title` -- HTML page title
|
|
75
|
-
- `options.config` -- object with `header` and `footer` strings
|
|
76
|
-
- `options.cssOverride` -- replaces the default stylesheet
|
|
77
|
-
- `options.cssAppend` -- appended after the base stylesheet
|
|
78
|
-
- Automatically extracts and applies `@meta` scope settings
|
|
79
|
-
}
|
|
80
|
-
}
|
|
81
|
-
|
|
82
|
-
# renderHtmlDocumentFromParsed(parsed, title, options)
|
|
83
|
-
{
|
|
84
|
-
Renders a complete HTML page from pre-parsed data. Use this when you need to parse and extract meta separately.
|
|
85
|
-
|
|
86
|
-
```javascript
|
|
87
|
-
const { parseSdoc, extractMeta, renderHtmlDocumentFromParsed } = require("@entropicwarrior/sdoc");
|
|
88
|
-
const parsed = parseSdoc(text);
|
|
89
|
-
const metaResult = extractMeta(parsed.nodes);
|
|
90
|
-
const html = renderHtmlDocumentFromParsed(
|
|
91
|
-
{ nodes: metaResult.nodes, errors: parsed.errors },
|
|
92
|
-
"Page Title",
|
|
93
|
-
{ meta: metaResult.meta }
|
|
94
|
-
);
|
|
95
|
-
```
|
|
96
|
-
}
|
|
97
|
-
|
|
98
|
-
# renderFragment(nodes, depth)
|
|
99
|
-
{
|
|
100
|
-
Renders an array of AST nodes to an HTML fragment (no `<html>` wrapper).
|
|
101
|
-
|
|
102
|
-
```javascript
|
|
103
|
-
const { parseSdoc, renderFragment } = require("@entropicwarrior/sdoc");
|
|
104
|
-
const { nodes } = parseSdoc(text);
|
|
105
|
-
const html = renderFragment(nodes, 2);
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
{[.]
|
|
109
|
-
- `nodes` -- array of AST nodes
|
|
110
|
-
- `depth` -- starting heading depth (default: 2)
|
|
111
|
-
}
|
|
112
|
-
}
|
|
113
|
-
|
|
114
|
-
# renderTextParagraphs(text)
|
|
115
|
-
{
|
|
116
|
-
Renders a plain text string as HTML paragraphs with inline formatting. Used internally for header/footer rendering from config values.
|
|
117
|
-
}
|
|
118
|
-
|
|
119
|
-
# formatSdoc(text, indentStr)
|
|
120
|
-
{
|
|
121
|
-
Reformats an SDOC string by adjusting indentation based on brace depth. Structure is not changed -- only whitespace is modified.
|
|
122
|
-
|
|
123
|
-
```javascript
|
|
124
|
-
const { formatSdoc } = require("@entropicwarrior/sdoc");
|
|
125
|
-
const formatted = formatSdoc(sdocText, " ");
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
{[.]
|
|
129
|
-
- `text` -- the SDOC source string
|
|
130
|
-
- `indentStr` -- the string to use for each indentation level (default: four spaces)
|
|
131
|
-
- Returns the reformatted string
|
|
132
|
-
- Code block content is passed through raw
|
|
133
|
-
- Inline blocks (`{ content }`) are kept on one line
|
|
134
|
-
- K&R style lines (heading ending with opener) are handled correctly
|
|
135
|
-
}
|
|
136
|
-
}
|
|
137
|
-
|
|
138
|
-
# resolveIncludes(nodes, resolverFn)
|
|
139
|
-
{
|
|
140
|
-
Walks the AST and resolves code blocks with `src` metadata by loading the referenced file contents. This is an async function.
|
|
141
|
-
|
|
142
|
-
```javascript
|
|
143
|
-
const { parseSdoc, resolveIncludes } = require("@entropicwarrior/sdoc");
|
|
144
|
-
const parsed = parseSdoc(text);
|
|
145
|
-
await resolveIncludes(parsed.nodes, async (src) => {
|
|
146
|
-
return fs.readFileSync(path.resolve(docDir, src), "utf8");
|
|
147
|
-
});
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
{[.]
|
|
151
|
-
- `nodes` -- the AST node array to walk (modified in place)
|
|
152
|
-
- `resolverFn` -- async function `(src) => string` that resolves a `src:` path to file contents
|
|
153
|
-
- Applies `lines` range filtering if present on the code node
|
|
154
|
-
- If the resolver throws, the code block text is set to an error message
|
|
155
|
-
}
|
|
156
|
-
}
|
|
157
|
-
|
|
158
|
-
# AST Node Types
|
|
159
|
-
{
|
|
160
|
-
The parser produces these node types:
|
|
161
|
-
|
|
162
|
-
{[.]
|
|
163
|
-
- `scope` -- a section with `title`, `id`, `children`, `hasHeading`, and optional `task`
|
|
164
|
-
- `paragraph` -- a text block with `text`
|
|
165
|
-
- `list` -- a list with `listType` (`"bullet"` or `"number"`) and `items`
|
|
166
|
-
- `blockquote` -- a quote with `paragraphs` (array of strings)
|
|
167
|
-
- `table` -- a table with `headers` (array of strings), `rows` (array of string arrays), and optional `options` (`{ borderless, headerless }`)
|
|
168
|
-
- `code` -- a code block with `lang`, `text`, and optional `src` (file path/URL) and `lines` (`{ start, end }`)
|
|
169
|
-
- `hr` -- a horizontal rule
|
|
170
|
-
}
|
|
171
|
-
|
|
172
|
-
Inline image nodes (`type: "image"`) within paragraphs include `src`, `alt`, and optional `width` (e.g. `"50%"`) and `align` (`"center"`, `"left"`, or `"right"`).
|
|
173
|
-
}
|
|
174
|
-
|
|
175
|
-
# exportSlidePdf(htmlPath, pdfPath)
|
|
176
|
-
{
|
|
177
|
-
Exports an HTML file to PDF using headless Chrome with 16:9 landscape dimensions (slide format).
|
|
178
|
-
|
|
179
|
-
```javascript
|
|
180
|
-
const { exportSlidePdf } = require("@entropicwarrior/sdoc/slide-pdf");
|
|
181
|
-
await exportSlidePdf("/tmp/slides.html", "/tmp/slides.pdf");
|
|
182
|
-
```
|
|
183
|
-
|
|
184
|
-
{[.]
|
|
185
|
-
- `htmlPath` -- path to the HTML file to convert
|
|
186
|
-
- `pdfPath` -- path for the output PDF
|
|
187
|
-
- Returns a Promise that resolves with the output path
|
|
188
|
-
- Requires Chrome or Chromium (auto-detected, or set `CHROME_PATH`)
|
|
189
|
-
}
|
|
190
|
-
}
|
|
191
|
-
|
|
192
|
-
# exportDocPdf(htmlPath, pdfPath)
|
|
193
|
-
{
|
|
194
|
-
Exports an HTML file to PDF using headless Chrome with A4 portrait dimensions (document format).
|
|
195
|
-
|
|
196
|
-
```javascript
|
|
197
|
-
const { exportDocPdf } = require("@entropicwarrior/sdoc/slide-pdf");
|
|
198
|
-
await exportDocPdf("/tmp/document.html", "/tmp/document.pdf");
|
|
199
|
-
```
|
|
200
|
-
|
|
201
|
-
{[.]
|
|
202
|
-
- `htmlPath` -- path to the HTML file to convert
|
|
203
|
-
- `pdfPath` -- path for the output PDF
|
|
204
|
-
- Returns a Promise that resolves with the output path
|
|
205
|
-
- Uses A4 paper (8.27 x 11.69 inches) with print-optimized styles
|
|
206
|
-
}
|
|
207
|
-
}
|
|
208
|
-
}
|
package/docs/reference/cli.sdoc
DELETED
|
@@ -1,188 +0,0 @@
|
|
|
1
|
-
# CLI and Tools Reference
|
|
2
|
-
{
|
|
3
|
-
@meta {
|
|
4
|
-
sdoc-version: 0.1
|
|
5
|
-
}
|
|
6
|
-
|
|
7
|
-
# VSCode Extension Commands
|
|
8
|
-
{
|
|
9
|
-
The SDOC extension registers eight commands, available from the Command Palette:
|
|
10
|
-
|
|
11
|
-
{[.]
|
|
12
|
-
- **SDOC: Open Preview** (`sdoc.preview`) -- opens a rendered preview of the current `.sdoc` file
|
|
13
|
-
- **SDOC: Open Preview to the Side** (`sdoc.previewToSide`) -- opens the preview in a side pane
|
|
14
|
-
- **SDOC: Export HTML** (`sdoc.exportHtml`) -- exports the current document as a standalone HTML file
|
|
15
|
-
- **SDOC: Export PDF** (`sdoc.exportPdf`) -- exports the current document as an A4 PDF via headless Chrome
|
|
16
|
-
- **SDOC: Open in Browser** (`sdoc.openInBrowser`) -- opens the current document in the system browser
|
|
17
|
-
- **SDOC: Browse Documents** (`sdoc.browseDocs`) -- starts a local document server and opens the viewer in a browser
|
|
18
|
-
- **SDOC: New Knowledge File** (`sdoc.newKnowledgeFile`) -- creates a new `.sdoc` file from a template in the selected folder
|
|
19
|
-
- **SDOC: Generate About** (`sdoc.generateAbout`) -- generates an About section for the current document
|
|
20
|
-
}
|
|
21
|
-
|
|
22
|
-
The preview updates automatically when the source file changes or when a `sdoc.config.json` or `.css` file is saved.
|
|
23
|
-
|
|
24
|
-
# Format Document
|
|
25
|
-
{
|
|
26
|
-
Use **Format Document** (Shift+Option+F on macOS, Shift+Alt+F on Windows/Linux) to auto-indent the current `.sdoc` file based on brace depth. The formatter respects VS Code's tab size and spaces/tabs preference. Code blocks are left untouched.
|
|
27
|
-
}
|
|
28
|
-
|
|
29
|
-
# Export HTML
|
|
30
|
-
{
|
|
31
|
-
Exports the current SDOC document as a self-contained `.html` file. Works from the editor or the preview panel. The exported file includes all styles and supports collapsible scope toggles in the browser.
|
|
32
|
-
}
|
|
33
|
-
|
|
34
|
-
# Export PDF
|
|
35
|
-
{
|
|
36
|
-
Exports the current SDOC document as an A4 PDF. Works from the editor or the preview panel. Requires Google Chrome or Chromium installed on the system (or set the `CHROME_PATH` environment variable). The PDF uses print-optimized styles with correct font sizes and preserved marker colors.
|
|
37
|
-
}
|
|
38
|
-
|
|
39
|
-
# Open in Browser
|
|
40
|
-
{
|
|
41
|
-
Opens the current SDOC document in the system's default browser. Works from the editor or the preview panel. A temporary HTML file is created and opened. Like Export HTML, the output supports collapsible toggles and printing.
|
|
42
|
-
}
|
|
43
|
-
}
|
|
44
|
-
|
|
45
|
-
# Build Document Tool
|
|
46
|
-
{
|
|
47
|
-
`tools/build-doc.js` exports SDOC files to HTML or PDF from the command line.
|
|
48
|
-
|
|
49
|
-
```bash
|
|
50
|
-
node tools/build-doc.js input.sdoc # PDF output (default)
|
|
51
|
-
node tools/build-doc.js input.sdoc -o output.pdf # PDF with custom path
|
|
52
|
-
node tools/build-doc.js input.sdoc --html # HTML output
|
|
53
|
-
node tools/build-doc.js input.sdoc --html -o out.html # HTML with custom path
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
# Options
|
|
57
|
-
{
|
|
58
|
-
{[.]
|
|
59
|
-
- `-o <path>` -- output file path (default: input name with `.pdf` or `.html` extension)
|
|
60
|
-
- `--html` -- export as HTML instead of PDF
|
|
61
|
-
- `--help` / `-h` -- show usage information and exit
|
|
62
|
-
}
|
|
63
|
-
}
|
|
64
|
-
|
|
65
|
-
PDF export requires Google Chrome or Chromium. Set the `CHROME_PATH` environment variable to override auto-detection. The output uses A4 page size with print-optimized styles.
|
|
66
|
-
|
|
67
|
-
The tool respects `sdoc.config.json` files in the directory hierarchy and per-file `@meta` style overrides, just like the VS Code extension.
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
# Notion Sync Tool
|
|
71
|
-
{
|
|
72
|
-
`tools/sync-notion.js` syncs SDOC files to Notion pages. See the [Notion Sync guide](../guide/notion-sync.sdoc) for full setup instructions.
|
|
73
|
-
|
|
74
|
-
```bash
|
|
75
|
-
node tools/sync-notion.js <file-or-directory> [options]
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
# Options
|
|
79
|
-
{
|
|
80
|
-
{[.]
|
|
81
|
-
- `--page-id <id>` -- override the Notion page ID (single-file mode only)
|
|
82
|
-
- `--token <tok>` -- Notion integration token (default: `$NOTION_TOKEN` env var)
|
|
83
|
-
- `--dry-run` -- render blocks to stdout without calling the Notion API
|
|
84
|
-
- `--verbose` -- print progress to stderr
|
|
85
|
-
- `--help` / `-h` -- show usage information and exit
|
|
86
|
-
}
|
|
87
|
-
}
|
|
88
|
-
|
|
89
|
-
# Examples
|
|
90
|
-
{
|
|
91
|
-
```bash
|
|
92
|
-
# Sync a single file (page ID from @meta)
|
|
93
|
-
node tools/sync-notion.js docs/architecture.sdoc --verbose
|
|
94
|
-
|
|
95
|
-
# Scan a directory for files with notion-page in @meta
|
|
96
|
-
node tools/sync-notion.js docs/ --verbose
|
|
97
|
-
|
|
98
|
-
# Dry run -- inspect the rendered Notion blocks
|
|
99
|
-
node tools/sync-notion.js docs/ --dry-run
|
|
100
|
-
|
|
101
|
-
# Override page ID (for testing)
|
|
102
|
-
node tools/sync-notion.js file.sdoc --page-id abc123def456
|
|
103
|
-
```
|
|
104
|
-
}
|
|
105
|
-
|
|
106
|
-
Files opt in to sync by setting `notion-page: <page-id>` in their `@meta` scope. When given a directory, the tool scans recursively for `.sdoc` files with this property.
|
|
107
|
-
}
|
|
108
|
-
|
|
109
|
-
# npm Package
|
|
110
|
-
{
|
|
111
|
-
The parser, renderers, and knowledge files are published to npm as `@entropicwarrior/sdoc`:
|
|
112
|
-
|
|
113
|
-
```bash
|
|
114
|
-
npm install @entropicwarrior/sdoc
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
See the [API reference](api.sdoc) for available exports.
|
|
118
|
-
}
|
|
119
|
-
|
|
120
|
-
# Building the Extension
|
|
121
|
-
{
|
|
122
|
-
```bash
|
|
123
|
-
npm install
|
|
124
|
-
npm run package
|
|
125
|
-
```
|
|
126
|
-
|
|
127
|
-
This produces `dist/sdoc-<version>.vsix`. Install it with:
|
|
128
|
-
|
|
129
|
-
```bash
|
|
130
|
-
code --install-extension dist/sdoc-<version>.vsix
|
|
131
|
-
```
|
|
132
|
-
}
|
|
133
|
-
|
|
134
|
-
# Document Server
|
|
135
|
-
{
|
|
136
|
-
Two ways to browse all `.sdoc` files in a project with a local HTTP server:
|
|
137
|
-
|
|
138
|
-
# Python CLI
|
|
139
|
-
{
|
|
140
|
-
`tools/serve_docs.py` starts a local document server:
|
|
141
|
-
|
|
142
|
-
```bash
|
|
143
|
-
python3 tools/serve_docs.py # serve current dir on :4070
|
|
144
|
-
python3 tools/serve_docs.py docs/ -p 8080 # serve docs/ on :8080
|
|
145
|
-
python3 tools/serve_docs.py --no-open # don't auto-open browser
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
{[.]
|
|
149
|
-
- `source_dir` (positional, default: `.`) -- directory containing `.sdoc` files
|
|
150
|
-
- `-p` / `--port` -- port to serve on (default: `4070`)
|
|
151
|
-
- `--no-open` -- don't open the browser automatically
|
|
152
|
-
}
|
|
153
|
-
}
|
|
154
|
-
|
|
155
|
-
# VSCode Command
|
|
156
|
-
{
|
|
157
|
-
Run **SDOC: Browse Documents** from the Command Palette. A prompt asks whether to serve the entire workspace or a specific folder. The server starts on an available port (4070-4079) and opens the viewer in the browser.
|
|
158
|
-
|
|
159
|
-
While the server is running, running the command again offers "Open in Browser" or "Stop Server". A status bar item shows the active port.
|
|
160
|
-
}
|
|
161
|
-
|
|
162
|
-
# How It Works
|
|
163
|
-
{
|
|
164
|
-
The server serves files directly from the source directory -- no copying, no bundling. The manifest (file list, titles, configs, CSS) is computed fresh on each request, so edits are reflected on browser refresh.
|
|
165
|
-
|
|
166
|
-
{[.]
|
|
167
|
-
- `GET /` -- viewer UI (`src/site-template/index.html`)
|
|
168
|
-
- `GET /viewer.css` -- viewer styles
|
|
169
|
-
- `GET /sdoc-web.js` -- browser-side parser/renderer
|
|
170
|
-
- `GET /api/manifest` -- file list, titles, configs, CSS map
|
|
171
|
-
- `GET /api/content?path=<rel>` -- raw `.sdoc` file content (on demand)
|
|
172
|
-
}
|
|
173
|
-
}
|
|
174
|
-
|
|
175
|
-
# Viewer Features
|
|
176
|
-
{
|
|
177
|
-
{[.]
|
|
178
|
-
- Sidebar with file tree navigation and search filtering
|
|
179
|
-
- Split-pane comparison (Shift+Click a second document)
|
|
180
|
-
- Collapsible sidebar with layout controls (single, split L/R, split T/B)
|
|
181
|
-
- Collapsible scopes (toggle triangles on scope headings, same as preview)
|
|
182
|
-
- Client-side rendering with the same parser as the extension
|
|
183
|
-
- Shadow DOM isolation for each document pane
|
|
184
|
-
- URL hash navigation (`#doc=path/to/file.sdoc`)
|
|
185
|
-
}
|
|
186
|
-
}
|
|
187
|
-
}
|
|
188
|
-
}
|