@entropicwarrior/sdoc 0.1.16 → 0.1.17

package/docs/reference/cli.sdoc

@@ -0,0 +1,188 @@
+# CLI and Tools Reference
+{
+    @meta {
+        sdoc-version: 0.1
+    }
+
+    # VSCode Extension Commands
+    {
+        The SDOC extension registers eight commands, available from the Command Palette:
+
+        {[.]
+            - **SDOC: Open Preview** (`sdoc.preview`) -- opens a rendered preview of the current `.sdoc` file
+            - **SDOC: Open Preview to the Side** (`sdoc.previewToSide`) -- opens the preview in a side pane
+            - **SDOC: Export HTML** (`sdoc.exportHtml`) -- exports the current document as a standalone HTML file
+            - **SDOC: Export PDF** (`sdoc.exportPdf`) -- exports the current document as an A4 PDF via headless Chrome
+            - **SDOC: Open in Browser** (`sdoc.openInBrowser`) -- opens the current document in the system browser
+            - **SDOC: Browse Documents** (`sdoc.browseDocs`) -- starts a local document server and opens the viewer in a browser
+            - **SDOC: New Knowledge File** (`sdoc.newKnowledgeFile`) -- creates a new `.sdoc` file from a template in the selected folder
+            - **SDOC: Generate About** (`sdoc.generateAbout`) -- generates an About section for the current document
+        }
+
+        The preview updates automatically when the source file changes or when a `sdoc.config.json` or `.css` file is saved.
+
+        # Format Document
+        {
+            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.
+        }
+
+        # Export HTML
+        {
+            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.
+        }
+
+        # Export PDF
+        {
+            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.
+        }
+
+        # Open in Browser
+        {
+            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.
+        }
+    }
+
+    # Build Document Tool
+    {
+        `tools/build-doc.js` exports SDOC files to HTML or PDF from the command line.
+
+        ```bash
+node tools/build-doc.js input.sdoc                   # PDF output (default)
+node tools/build-doc.js input.sdoc -o output.pdf      # PDF with custom path
+node tools/build-doc.js input.sdoc --html             # HTML output
+node tools/build-doc.js input.sdoc --html -o out.html  # HTML with custom path
+        ```
+
+        # Options
+        {
+            {[.]
+                - `-o <path>` -- output file path (default: input name with `.pdf` or `.html` extension)
+                - `--html` -- export as HTML instead of PDF
+                - `--help` / `-h` -- show usage information and exit
+            }
+        }
+
+        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.
+
+        The tool respects `sdoc.config.json` files in the directory hierarchy and per-file `@meta` style overrides, just like the VS Code extension.
+    }
+
+    # Notion Sync Tool
+    {
+        `tools/sync-notion.js` syncs SDOC files to Notion pages. See the [Notion Sync guide](../guide/notion-sync.sdoc) for full setup instructions.
+
+        ```bash
+node tools/sync-notion.js <file-or-directory> [options]
+        ```
+
+        # Options
+        {
+            {[.]
+                - `--page-id <id>` -- override the Notion page ID (single-file mode only)
+                - `--token <tok>` -- Notion integration token (default: `$NOTION_TOKEN` env var)
+                - `--dry-run` -- render blocks to stdout without calling the Notion API
+                - `--verbose` -- print progress to stderr
+                - `--help` / `-h` -- show usage information and exit
+            }
+        }
+
+        # Examples
+        {
+            ```bash
+# Sync a single file (page ID from @meta)
+node tools/sync-notion.js docs/architecture.sdoc --verbose
+
+# Scan a directory for files with notion-page in @meta
+node tools/sync-notion.js docs/ --verbose
+
+# Dry run -- inspect the rendered Notion blocks
+node tools/sync-notion.js docs/ --dry-run
+
+# Override page ID (for testing)
+node tools/sync-notion.js file.sdoc --page-id abc123def456
+            ```
+        }
+
+        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.
+    }
+
+    # npm Package
+    {
+        The parser, renderers, and knowledge files are published to npm as `@entropicwarrior/sdoc`:
+
+        ```bash
+npm install @entropicwarrior/sdoc
+        ```
+
+        See the [API reference](api.sdoc) for available exports.
+    }
+
+    # Building the Extension
+    {
+        ```bash
+npm install
+npm run package
+        ```
+
+        This produces `dist/sdoc-<version>.vsix`. Install it with:
+
+        ```bash
+code --install-extension dist/sdoc-<version>.vsix
+        ```
+    }
+
+    # Document Server
+    {
+        Two ways to browse all `.sdoc` files in a project with a local HTTP server:
+
+        # Python CLI
+        {
+            `tools/serve_docs.py` starts a local document server:
+
+            ```bash
+python3 tools/serve_docs.py                          # serve current dir on :4070
+python3 tools/serve_docs.py docs/ -p 8080            # serve docs/ on :8080
+python3 tools/serve_docs.py --no-open                # don't auto-open browser
+            ```
+
+            {[.]
+                - `source_dir` (positional, default: `.`) -- directory containing `.sdoc` files
+                - `-p` / `--port` -- port to serve on (default: `4070`)
+                - `--no-open` -- don't open the browser automatically
+            }
+        }
+
+        # VSCode Command
+        {
+            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.
+
+            While the server is running, running the command again offers "Open in Browser" or "Stop Server". A status bar item shows the active port.
+        }
+
+        # How It Works
+        {
+            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.
+
+            {[.]
+                - `GET /` -- viewer UI (`src/site-template/index.html`)
+                - `GET /viewer.css` -- viewer styles
+                - `GET /sdoc-web.js` -- browser-side parser/renderer
+                - `GET /api/manifest` -- file list, titles, configs, CSS map
+                - `GET /api/content?path=<rel>` -- raw `.sdoc` file content (on demand)
+            }
+        }
+
+        # Viewer Features
+        {
+            {[.]
+                - Sidebar with file tree navigation and search filtering
+                - Split-pane comparison (Shift+Click a second document)
+                - Collapsible sidebar with layout controls (single, split L/R, split T/B)
+                - Collapsible scopes (toggle triangles on scope headings, same as preview)
+                - Client-side rendering with the same parser as the extension
+                - Shadow DOM isolation for each document pane
+                - URL hash navigation (`#doc=path/to/file.sdoc`)
+            }
+        }
+    }
+}

package/{lexica → docs/reference}/sdoc-authoring.sdoc

@@ -84,6 +84,51 @@
             document.
         }
 
+        # Headingless Scopes @headingless-scopes
+        {
+            A bare \`{ }\` block without a heading creates a section with no title — useful for grouping content:
+
+            ```
+            {
+                This content is grouped but has no heading.
+            }
+            ```
+
+            Headingless scopes nest like any other scope and can appear anywhere a headed scope can.
+        }
+
+        # Inline Blocks @inline-blocks
+        {
+            Short content can be written on a single line:
+
+            ```
+            # Author
+            { Jane Doe }
+
+            # Version
+            { 1.0 }
+            ```
+
+            Inline blocks must not contain unescaped \`{\` or \`}\` characters.
+        }
+
+        # Implicit Root @implicit-root
+        {
+            If the first heading is not followed by \`{\`, the document uses implicit root mode — the first heading becomes the document title and everything after it becomes the body:
+
+            ```
+# My Document
+
+# Section A
+Content of Section A.
+
+# Section B
+Content of Section B.
+            ```
+
+            This is equivalent to wrapping the entire body in braces after the first heading. Use implicit root for simple flat documents.
+        }
+
         # Paragraphs @paragraphs
         {
             Consecutive text lines form a paragraph. A blank line or a new scope
@@ -134,6 +179,38 @@
             **Important:** \`{[.]}\` with the closing brace on the same line creates an empty list — the brace closes the block immediately. Always put the closing \`}\` on a separate line after the items.
 
             Implicit lists only work for bullet lists (\`-\`) where every item is a single line. For numbered lists, always use the explicit \`{[#]\` block form.
+
+            **Task lists** — checkbox syntax inside explicit list blocks:
+
+            ```
+            {[.]
+                - [ ] Pending task
+                - [x] Completed task
+            }
+            ```
+
+            **Anonymous list items** — items with no title, just a body block:
+
+            ```
+            {[.]
+                {
+                    First item, body only.
+                }
+                {
+                    Second item, body only.
+                }
+            }
+            ```
+
+            **Multi-line titles** — in explicit list blocks, item titles can span multiple lines. Continuation stops at blank lines, list markers, braces, and other command tokens:
+
+            ```
+            {[.]
+                - This is a long list item
+                  that continues on the next line
+                - Short item
+            }
+            ```
         }
 
         # Tables @tables
@@ -286,6 +363,15 @@
             ```
         }
 
+        # Horizontal Rules @horizontal-rules
+        {
+            A line of three or more \`-\`, \`*\`, or \`_\`:
+
+            ```
+            ---
+            ```
+        }
+
         # Meta Scope @meta-scope
         {
             The reserved \`@meta\` scope configures per-file settings and is not rendered in the document body. Use the bare \`@meta\` form (preferred) or the heading form:
@@ -359,6 +445,15 @@
 
             A line starting with \`\\#\` renders as a literal \`#\` (not a heading). Use \`\\\$\` to prevent a dollar sign from starting math mode.
         }
+
+        # Conventions @conventions
+        {
+            {[.]
+                - **Indentation:** cosmetic — use any whitespace you like. Most authors use 4 spaces.
+                - **IDs:** lowercase kebab-case (\`@my-section\`). IDs should be unique within a document.
+                - **Commas:** commas between list items or scopes are allowed but ignored — use them if you find them readable.
+            }
+        }
     }
 
     # Common Mistakes @common-mistakes