HyperDoc 2.0

.github/workflows/extension-ci.yml

@@ -0,0 +1,75 @@
+name: Extension CI
+
+on:
+  pull_request:
+    branches: [master, hdoc-2.0]
+  push:
+    branches: [master, hdoc-2.0]
+
+jobs:
+  build-and-package:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Zig
+        uses: mlugg/setup-zig@v2
+        with:
+          version: 0.15.2
+
+      - name: Build Zig artifacts
+        run: zig build install
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install extension dependencies
+        run: npm ci
+        working-directory: vscode-ext
+
+      - name: Copy wasm artifacts into extension bundle
+        run: |
+          mkdir -p vscode-ext/wasm
+          cp zig-out/www/hyperdoc_wasm.wasm vscode-ext/wasm/ || true
+          cp zig-out/www/hyperdoc_wasm_lsp.wasm vscode-ext/wasm/
+
+      - name: Build extension
+        run: npm run compile
+        working-directory: vscode-ext
+
+      - name: Test extension
+        run: npm test
+        working-directory: vscode-ext
+
+      - name: Package extension
+        run: |
+          npm run package
+          mv *.vsix hyperdoc-vscode.vsix
+        working-directory: vscode-ext
+
+      - name: Upload packaged extension
+        uses: actions/upload-artifact@v4
+        with:
+          name: hyperdoc-vscode.vsix
+          path: vscode-ext/hyperdoc-vscode.vsix
+
+  publish:
+    needs: build-and-package
+    if: github.event_name == 'push' && github.ref == 'refs/heads/hdoc-2.0'
+    runs-on: ubuntu-latest
+    environment:
+      name: vscode-marketplace
+    steps:
+      - name: Download packaged extension
+        uses: actions/download-artifact@v4
+        with:
+          name: hyperdoc-vscode.vsix
+          path: artifacts
+
+      - name: Publish to VS Code Marketplace
+        run: npx --yes vsce publish --packagePath artifacts/hyperdoc-vscode.vsix -p "$VSCE_PAT"
+        env:
+          VSCE_PAT: ${{ secrets.VSCE_PAT }}

.github/workflows/pages.yml

@@ -0,0 +1,42 @@
+name: Pages
+
+on:
+  push:
+    branches: [hdoc-2.0]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+    environment:
+      name: github-pages
+      url: ${{steps.deployment.outputs.page_url}}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup Zig
+        uses: mlugg/setup-zig@v2
+        with:
+          version: 0.15.2
+
+      - name: Build
+        run: |
+          zig build install
+
+      - name: Test
+        run: |
+          zig build test
+
+      - name: Upload static files as artifact
+        id: pages-upload
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: zig-out/www
+
+      - name: Deploy artifact
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/validate.yml

@@ -2,9 +2,9 @@ name: Build
 
 on:
   pull_request:
-    branches: [master]
+    branches: [master, hdoc-2.0]
   push:
-    branches: [master]
+    branches: [master, hdoc-2.0]
 
 jobs:
   build:
@@ -16,8 +16,12 @@ jobs:
       - name: Setup Zig
         uses: mlugg/setup-zig@v2
         with:
-          version: 0.15.1
+          version: 0.15.2
 
       - name: Build
         run: |
-          zig build
+          zig build install
+
+      - name: Test
+        run: |
+          zig build test

AGENTS.md

@@ -0,0 +1,30 @@
+# AGENTS
+
+## General guidelines
+
+- Keep changes focused and incremental; prefer small, reviewable commits.
+- Follow existing code style and formatting conventions.
+- Use `zig fmt` on Zig source files after edits.
+- Ensure new tests are added or updated when behavior changes.
+- Run relevant tests (`zig build test`) when making code changes.
+- Run `zig build` to validate the main application still compiles
+- Test `./zig-out/bin/hyperdoc` with the `.hdoc` files in `examples/` and `test/`.
+- Avoid editing documentation unless the request explicitly asks for it.
+- `src/hyperdoc.zig` must not contain locale- or rendering-specific parts.
+- Treat `docs/specification.md` as the authoritative source of behavior; examples may be outdated or incorrect.
+- If the spec is unclear or conflicts with code/tests, ask before changing behavior.
+- Do not implement "just make it work" fallbacks that alter semantics to satisfy examples.
+- Diagnostics must not store dynamic strings (e.g., slices to parsed source). Keep diagnostic payloads POD/small and avoid holding arena-backed text.
+- Do not hide crashes by removing safety checks or switching off DebugAllocator; fix the root cause instead. A signal 6 from DebugAllocator indicates memory corruption or a similar misuse.
+
+## Zig Programming Style
+
+- Do not use "inline functions" like `const func = struct { fn func(…) {} }.func;`
+- Zig has no methods. Functions used by "method like" functions can still be placed next to them, no need to put them into global scope nor into local scope.
+
+## Snapshot Files
+
+- If you add a `hdoc` file to `test/snapshot`, also:
+  - Generate the corresponding html and yaml file
+  - Add the file inside build.zig to the snapshot_files global
+- If you change behaviour, the snapshot tests will fail. Validate the failure against your expectations and see if you broke something unexpected.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HyperDoc Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,62 +1,33 @@
 # Ashet HyperDocument Format
 
-This format is used for both the _Hyper Wiki_ as well as the _Gateway_ application to store and display
-hyperlinked documents.
-
-The format is a rich-text format that can encode/store/display the following document blocks:
-
-- paragraphs (consisting of a sequence of spans)
-  - regular text
-  - links
-  - bold/emphasised text
-  - monospaced text
-  - line break
-- 3 levels of headings
-- ordered and unordered lists
-  - each list item is a paragraph or another list
-- quotes (paragraph with special styling)
-- preformatted text (code blocks, also uses the paragraph formatting)
-- images
-
-Regular text is assumed to use a proportional font, while preformatted text is required to be rendered as monospace.
-
-## Storage
-
-HyperDocument is stored as a trivial-to-parse plain text format, not necessarily meant to be edited by humans,
-but still human readable.
-
-**Example:**
-
-```lua
-hdoc "1.0"
-p {
-  span "Hello, World!\n"
-  link "http://google.com" "Visit Google!"
-  span "\n"
-  emph "This is fat!"
-  span "\n"
-  mono "int main()"
-  span "\n"
-}
-enumerate {
-  item { p { span "first" } }
-  item { p { span "second" } }
-  item { p { span "third" } }
-}
-itemize {
-  item { p { span "first" } }
-  item { p { span "second" } }
-  item { p { span "third" } }
-}
-quote {
-  span "Life is what happens when you're busy making other plans.\n - John Lennon"
-}
-pre {
-  span "const std = @import(\"std\");\n"
-  span "\n"
-  span "pub fn main() !void {\n"
-  span "    std.debug.print(\"Hello, World!\\n\", .{});\n"
-  span "}\n"
-}
-image "dog.png"
+## Motivation
+
+> TODO: Write motivation
+
+## Specification
+
+[Read the specification](docs/specification.md).
+
+## Building
+
+Requires [Zig 0.15.2](https://ziglang.org/) installed.
+
+### Build debug application
+
+```sh-session
+[user@host] hyperdoc$ zig build
 ```
+
+### Build release application
+
+```sh-session
+[user@host] hyperdoc$ zig build -Drelease
+```
+
+### Run test suite
+
+```sh-session
+[user@host] hyperdoc$ zig build test
+```
+
+> Optional: installing Node.js enables the WASM integration tests that exercise the compiled `hyperdoc_wasm.wasm` via `node test/wasm/validate.js`.

SPEC_TODO.md

@@ -0,0 +1,6 @@
+# Spec compliance TODOs
+
+- Title/header interplay lacks the required comparison.  
+  - Expect: When both `hdoc(title=...)` and `title { ... }` are present, their plaintext forms are compared and a redundancy hint is emitted if they match (§8.1).  
+  - Actual: The block title is used and the header title is ignored without any comparison or diagnostics.  
+  - Proposed: Compare the plaintext values, warn when redundant, and keep emitting hints when neither title form is present.