apex-ruby 1.0.17 → 1.0.20

data/ext/apex_ext/apex_src/buildnotes.md

@@ -0,0 +1,1435 @@
+template: project, github
+project: apex
+readme: src/_README.md
+changelog: CHANGELOG.md
+
+# Apex Build Notes
+
+Comprehensive guide for building, testing, and working with the Apex Markdown processor.
+
+This document works with [Howzit](https://brettterpstra.com/projects/howzit).
+
+## Clone repository
+
+```run Clone from GitHub
+#!/bin/bash
+
+git clone git@github.com:ApexMarkdown/apex
+cd apex
+git submodule update --init --recursive
+```
+
+## Setup build directory
+
+```run Make build dir and run cmake
+#!/bin/bash
+
+mkdir -p build
+cd build
+cmake ..
+```
+
+## Build all
+
+Builds cli, shared library, test runner, and framework.
+
+@run(cmake --build build) Cmake build
+
+## Build CLI tool
+
+Build just the CLI tool.
+
+@run(cmake --build build --target apex_cli) Build CLI tool
+
+## Build shared library
+
+Build just the shared library.
+
+@run(cmake --build build --target apex)
+
+## Just static library
+
+Build just the static library.
+
+@run(cmake --build build --target apex_static)
+
+## Build macOS framework
+
+Build the framework for Xcode.
+
+@run(cmake --build build --target apex_framework)
+
+## Build test runner
+
+Build just the test runner.
+
+@run(cmake --build build --target apex_test_runner &>/dev/null) Build test runner
+
+## Build with Address Sanitizer
+
+Build with AddressSanitizer and UndefinedBehaviorSanitizer for detecting memory errors and undefined behavior. This is useful for debugging crashes and assertion failures.
+
+```run Build ASan
+#!/bin/bash
+
+mkdir -p build-asan
+cd build-asan
+cmake .. -DCMAKE_BUILD_TYPE=ASan
+cmake --build .
+```
+
+## Run with Address Santizer
+
+@include(Build with Address Santizer)
+
+After building, run tests with:
+
+@run(./build-asan/apex_test_runner advanced_tables) Run with ASan
+
+## Clean build
+
+Delete the build directory and run `cmake` clean.
+
+```run Clean all targets
+#!/bin/bash
+
+cd build
+cmake --build . --target clean
+```
+
+## Rebuild from scratch
+
+Delete the build directory and build all.
+
+```run Delete build directory and build fresh
+#!/bin/bash
+
+rm -rf build
+mkdir build && cd build
+cmake ..
+cmake --build .
+```
+
+## List Available Tests (search:"")
+
+List all available tests, or search for a matching test.
+
+```run List tests
+#!/usr/bin/env ruby
+
+$files = `./build/apex_test_runner list`.strip.split(/\n/)
+search = "${search}"
+
+def normalize_suite(suite)
+  if suite && !suite.empty?
+    suite = suite.split('').join('.*')
+    $files.delete_if { |f| f !~ /#{suite}/ }
+  end
+  $files
+end
+
+puts normalize_suite(search)
+```
+
+## Run tests (suite:all, errors_only:false)
+
+Build and run the test runner. If suite argument is anything other than "all", run specific suite(s). If errors argument is "errors", "true", or "yes", only show errors.
+
+@include(Build CLI)
+@include(Build test runner)
+
+```run Run tests
+#!/usr/bin/env ruby
+require 'English'
+
+errors_only = "${errors_only}" =~ /^[ety]/i ? '--errors-only ' : ''
+suite = "${suite}"
+out = ""
+code = 0
+
+def normalize_suite(suite)
+  files = `./build/apex_test_runner list`.strip.split(/\n/)
+
+  if suite && !suite.empty?
+    suite = suite.split('').join('.*')
+    files.delete_if { |f| f !~ /#{suite}/ }
+  end
+  files
+end
+
+if suite =~ /^all$/i
+  out = `./build/apex_test_runner #{errors_only} 2>&1`
+  code = $CHILD_STATUS.exitstatus
+else
+  test_files = normalize_suite(suite)
+
+  test_files.each do |file|
+    puts "Running #{file} tests"
+    out += `./build/apex_test_runner #{file} #{errors_only} 2>&1`
+    if $CHILD_STATUS.exitstatus != 0
+      code = $CHILD_STATUS.exitstatus
+    end
+  end
+end
+
+puts out
+
+exit code
+```
+
+@include(Multi-file CLI tests)
+
+@include(Metadata CLI tests)
+
+@include(Test Swift Package)
+
+## Profile Execution (file:tests/fixtures/comprehensive_test.md)
+
+@run(APEX_PROFILE=true build/apex "${file}")
+
+## Profile Plugins (file:tests/fixtures/comprehensive_test.md)
+
+@run(APEX_PROFILE_PLUGINS=true build/apex --plugins "${file}")
+
+## Profile All (file:tests/fixtures/comprehensive_test.md)
+
+@run(APEX_PROFILE_PLUGINS=true APEX_PROFILE=true build/apex --plugins "${file}")
+
+## Test Swift Package
+
+```run
+#!/bin/bash
+cmake --build build --target swift_package_check
+cmake --build build --target swift_package_check_release
+```
+
+## Multi-file CLI tests
+
+In addition to the C test runner, there is a small shell script that exercises the **CLI** multi-file features (`--combine` and `--mmd-merge`) against the `tests/fixtures/combine_summary` fixtures:
+
+```run Run multi-file CLI tests
+#!/bin/bash
+
+./tests/multi_file_cli_test.sh
+```
+
+This script is intentionally separate from `apex_test_runner` because it tests the command-line interface behavior (flags, piping, and index files) rather than the core library API. Run it after rebuilding `build/apex` when you change multi-file behavior.
+
+## Metadata CLI tests
+
+Shell tests for **`--info`**, **`--extract-meta`**, and **`--extract-meta-value`** using `tests/fixtures/metadata` (YAML front matter, MultiMarkdown metadata, and Pandoc title lines).
+
+```run Run metadata CLI tests
+#!/bin/bash
+
+./tests/metadata_cli_test.sh
+```
+
+Run after rebuilding `build/apex` when you change metadata extraction or CLI info output.
+
+## Test basic conversion
+
+Render the most basic string.
+
+@run(echo "# Test Header" | ./build/apex)
+
+## Test with file (file)
+
+Render the most basic file.
+
+@run(./build/apex "${file:filetests/test_basic.md}") Render basic file
+
+## Test CommonMark mode (file)
+
+@run(./build/apex --mode commonmark "${file:tests/test_basic.md}") Render with CommonMark
+
+## Test GFM mode (file)
+
+@run(./build/apex --mode gfm "${file:tests/test_basic.md}") Render with GFM
+
+## Test MultiMarkdown mode (file)
+
+@run(./build/apex --mode multimarkdown "${file:tests/test_basic.md}") Render with MMD
+
+## Test Kramdown mode (file)
+
+@run(./build/apex --mode kramdown "${file:tests/test_basic.md}") Render with Kramdown
+
+## Test standalone output (file)
+
+@run(./build/apex --standalone --title "Test" "${file:tests/test_basic.md}") Render standalone
+
+## Test pretty-print (file)
+
+@run(./build/apex --pretty "${file:tests/test_basic.md}") Render pretty print
+
+## Install (prefix)
+
+Include an argument with path to change install location.
+
+```run Install to ${prefix} with sudo
+#!/bin/bash
+
+cd build
+cmake -DCMAKE_INSTALL_PREFIX=${prefix:/usr/local} ..
+make
+sudo make install
+```
+
+## Build with debug symbols
+
+```run Build debug
+#!/bin/bash
+
+mkdir -p build_debug
+cd build_debug
+cmake -DCMAKE_BUILD_TYPE=Debug ..
+cmake --build .
+```
+
+## Run with debugger
+
+@run(lldb ./build/apex) Run with lldb
+
+**Common lldb commands**:
+
+```bash
+# Set breakpoint by function name
+(lldb) breakpoint set --name apex_markdown_to_html
+(lldb) br s -n apex_markdown_to_html
+
+# Set breakpoint at file:line
+(lldb) breakpoint set --file apex.c --line 100
+(lldb) br s -f apex.c -l 100
+
+# List breakpoints
+(lldb) breakpoint list
+(lldb) br list
+
+# Run the program with arguments
+(lldb) run document.md
+(lldb) r document.md
+(lldb) r --mode multimarkdown document.md
+
+# Run with stdin
+(lldb) r < input.md
+
+# Step over (next line)
+(lldb) next
+(lldb) n
+
+# Step into (enter function)
+(lldb) step
+(lldb) s
+
+# Continue execution
+(lldb) continue
+(lldb) c
+
+# Print variable
+(lldb) print options
+(lldb) p options
+(lldb) p options.enable_tables
+
+# Print string
+(lldb) p (char*)html
+(lldb) p/s html
+
+# Examine memory
+(lldb) x/s markdown
+(lldb) memory read --size 100 markdown
+
+# Show backtrace (call stack)
+(lldb) bt
+(lldb) thread backtrace
+
+# List source code
+(lldb) list
+(lldb) l
+
+# Show current frame
+(lldb) frame info
+
+# Move up/down call stack
+(lldb) up
+(lldb) down
+
+# Watch variable
+(lldb) watchpoint set variable html
+(lldb) watchpoint list
+
+# Delete breakpoint
+(lldb) breakpoint delete 1
+(lldb) br del 1
+
+# Delete all breakpoints
+(lldb) breakpoint delete
+(lldb) br del
+
+# Exit
+(lldb) quit
+(lldb) q
+```
+
+**Debugging specific issues**:
+
+```bash
+# Debug crash
+lldb ./build/apex
+(lldb) r document.md
+# When it crashes:
+(lldb) bt
+(lldb) frame variable
+
+# Debug with specific mode
+lldb ./build/apex
+(lldb) r --mode kramdown tests/test_basic.md
+
+# Debug preprocessing step
+lldb ./build/apex
+(lldb) br s -n apex_process_includes
+(lldb) r --enable-includes document.md
+(lldb) p text_ptr
+
+# Debug extension
+lldb ./build/apex
+(lldb) br s -f wiki_links.c -l 50
+(lldb) r document.md
+```
+
+## Check for memory leaks
+
+@run(leaks --atExit -- ./build/apex tests/test_basic.md) Check for leaks
+
+## Build verbose
+
+@run(cmake --build build -- VERBOSE=1) Build verbosely
+
+## Benchmark conversion
+
+@run(time ./build/apex tests/test_basic.md > /dev/null) Basic benchmark
+
+## Detailed Benchmarks
+
+@run(./tests/benchmark.sh) Detailed benchmark with averages
+
+## Comparison Benchmarks
+
+@run(./tests/benchmark_comparison.sh) Detailed benchmark comparing processors
+
+## Update Benchmark Markdown
+
+Runs both benchmark scripts, outputs to Markdown files, and commits to the repo.
+
+```run Run benchmark scripts and output to Markdown files
+#!/bin/bash
+cd $HOME/Desktop/Code/apex
+
+./tests/benchmark.sh >BENCHMARK.md
+./tests/benchmark_comparison.sh >BENCHMARK_COMPARISON.md
+```
+
+```run? Commit to Apex repo
+git add BENCHMARK.md BENCHMARK_COMPARISON.md
+git commit -m "Update benchmarks"
+```
+
+## Generate Xcode project
+
+```run Generate the xcode project
+#!/bin/bash
+
+mkdir -p xcode_build
+cd xcode_build
+cmake -G Xcode ..
+```
+
+@run?!(open Apex.xcodeproj) Open in Xcode
+
+## Fix cmark-gfm submodule
+
+```run Make the cmark-gfm submodule
+#!/bin/bash
+
+git submodule update --init --recursive
+cd vendor/cmark-gfm
+mkdir -p build && cd build
+cmake ..
+make
+```
+
+## Convert standalone document and paginate (file)
+
+@run(build/apex "${file}" --standalone --wikilinks | bat) Convert and pipe to bat
+
+## Convert standalone document and open in browser (file)
+
+@run(build/apex "${file}" --standalone --wikilinks | bcat) Convert and pipe to bcat
+
+## Convert document fragment (file)
+
+```run Convert file as snippet to output.html
+#!/bin/bash
+
+# Compact HTML fragment (default)
+./build/apex "${file}" > output.html
+```
+
+## Convert with pretty-print (file)
+
+```run Pretty print file to output.html
+#!/bin/bash
+
+# Pretty-formatted HTML
+./build/apex --pretty "${file}" > output.html
+```
+
+## Convert standalone document (file, title)
+
+```run Convert file to standalone output.html with title
+#!/bin/bash
+
+# Complete HTML5 document
+./build/apex --standalone --title "${title:Document}" "${file}" > output.html
+```
+
+## Convert with custom CSS (title,stylesheet)
+
+```run
+#!/bin/bash
+
+# Standalone with custom CSS
+./build/apex -s --title "[%title:Document]" --style [%stylesheet:styles.css] document.md > output.html
+```
+
+## Convert beautiful complete doc (title,stylesheet)
+
+```run
+#!/bin/bash
+
+# Standalone + pretty + custom CSS
+./build/apex -s --pretty --title "[%title:Document]" --style [%stylesheet:styles.css] document.md -o output.html
+```
+
+## Process Critic Markup with changes visible
+
+```run
+#!/bin/bash
+
+# Show markup with HTML tags (default)
+./build/apex document.md > review.html
+```
+
+## Process Critic Markup accept changes
+
+```run
+#!/bin/bash
+
+# Accept all changes, clean output
+./build/apex --accept draft.md > final.html
+```
+
+## Process Critic Markup reject changes
+
+```run
+#!/bin/bash
+
+# Reject all changes, revert to original
+./build/apex --reject draft.md > original.html
+```
+
+## Convert with file includes
+
+```run
+#!/bin/bash
+
+# Enable file transclusion
+./build/apex --enable-includes document.md > output.html
+```
+
+## View help
+
+@run(./build/apex --help)
+
+## View version
+
+@run(./build/apex --version)
+
+## Project Structure
+
+**Source organization**:
+
+- `src/apex.c` - Core processor
+- `src/extensions/` - Feature extensions (18 modules)
+- `src/pretty_html.c` - Pretty-print formatter
+- `src/html_renderer.c` - Custom HTML renderer
+- `include/apex/apex.h` - Public API
+- `cli/main.c` - CLI interface
+- `tests/test_runner.c` - Test suite (187 tests)
+- `tests/fixtures/` - Test data files
+- `docs/` - Documentation (16 files)
+- `vendor/cmark-gfm/` - Base parser (submodule)
+
+## Build Targets
+
+**Available CMake targets**:
+
+- `apex_cli` - Command-line tool
+- `apex` - Shared library
+- `apex_static` - Static library
+- `apex_framework` - macOS framework (macOS only)
+- `apex_test_runner` - Test suite
+- `cmark-gfm` - Vendor dependency (auto-built)
+
+## Common Options
+
+**Processor modes** (`--mode`):
+
+- `commonmark` - Pure CommonMark spec
+- `gfm` - GitHub Flavored Markdown
+- `multimarkdown` / `mmd` - MultiMarkdown compatibility
+- `kramdown` - Kramdown compatibility
+- `unified` - All features enabled (default)
+
+**Output formats**:
+
+- Default - Compact HTML fragment
+- `--pretty` - Formatted HTML with indentation
+- `--standalone` / `-s` - Complete HTML5 document
+- `-s --pretty` - Beautiful complete document
+
+**Critic Markup modes**:
+
+- Default - Show markup with HTML tags
+- `--accept` - Apply all changes
+- `--reject` - Revert all changes
+
+**Feature toggles**:
+
+- `--enable-includes` - File transclusion
+- `--no-tables` - Disable tables
+- `--no-footnotes` - Disable footnotes
+- `--no-smart` - Disable smart typography
+- `--no-math` - Disable math
+- `--hardbreaks` - Treat newlines as hard breaks
+
+**Document options** (standalone mode):
+
+- `--title TITLE` - Set document title
+- `--style FILE` - Link external CSS
+
+## Test Coverage
+
+**Current status**:
+
+- Total tests: 187
+- Passing: 187 (100%)
+- Coverage: 95%
+- Test file: `tests/test_runner.c` (1,089 lines)
+
+**Test categories**:
+
+- Basic Markdown (5 tests)
+- GFM Features (5 tests)
+- Metadata (4 tests)
+- Wiki Links (3 tests)
+- Math (4 tests)
+- Critic Markup (13 tests)
+- Processor Modes (4 tests)
+- File Includes (16 tests)
+- IAL (5 tests)
+- Definition Lists (11 tests)
+- Advanced Tables (6 tests)
+- Callouts (10 tests)
+- TOC Generation (14 tests)
+- HTML Markdown (9 tests)
+- Abbreviations (11 tests)
+- Emoji (10 tests)
+- Special Markers (7 tests)
+- Footnotes (10 tests)
+- Standalone Output (14 tests)
+- Pretty-Print (11 tests)
+
+## Documentation Files
+
+**Available documentation** (17 files):
+
+- `README.md` - Project overview
+- `buildnotes.md` - This file
+- `docs/USER_GUIDE.md` - User documentation (693 lines)
+- `docs/API_REFERENCE.md` - C API reference
+- `docs/ARCHITECTURE.md` - System design
+- `docs/CRITICMARKUP.md` - Critic Markup guide
+- `docs/OUTPUT_MODES.md` - Output format guide
+- `docs/STANDALONE_FEATURE.md` - Standalone mode guide
+- `docs/CMARK_INTEGRATION.md` - cmark-gfm integration
+- `docs/MARKED_INTEGRATION.md` - Marked app integration
+- `docs/INTEGRATION_EXAMPLE.m` - Objective-C example
+- `docs/TEST_COVERAGE.md` - Test analysis
+- `docs/LIMITATIONS_RESOLVED.md` - Resolved issues
+- `docs/FINAL_STATUS_UPDATE.md` - Project status
+- `docs/FUTURE_FEATURES.md` - Feature roadmap
+- `docs/PROGRESS.md` - Development progress
+- `docs/WIKI_LINKS_ISSUE.md` - Technical note
+
+## Features
+
+**40+ features across 5 Markdown flavors**:
+
+- CommonMark compliance
+- GitHub Flavored Markdown (tables, strikethrough, task lists, autolinks)
+- MultiMarkdown (metadata, transclusion, abbreviations, smart typography)
+- Kramdown (IAL, definition lists, attributes)
+- Marked special syntax (callouts, wiki links, file includes, TOC)
+
+**Key features**:
+
+- 3 abbreviation syntaxes (classic MMD, MMD 6 reference, MMD 6 inline)
+- 3 footnote syntaxes (reference, Kramdown inline, MMD inline)
+- 3 file include syntaxes (Marked, MMD, iA Writer)
+- Advanced tables (rowspan, colspan, captions)
+- Critic Markup with accept/reject modes
+- GitHub emoji (350+)
+- Math support (LaTeX)
+- Definition lists with Markdown content
+- TOC generation with depth control
+- Standalone HTML output with CSS
+- Pretty-print formatting
+
+## Requirements
+
+**Build requirements**:
+
+- CMake 3.10+
+- C compiler (GCC, Clang, MSVC)
+- Git
+
+**Runtime**:
+
+- No dependencies (statically linked)
+- macOS 10.13+ / Linux / Windows
+
+## Version
+
+**Current version**: 0.1.0
+
+Defined in `include/apex/apex.h`:
+
+- `APEX_VERSION_MAJOR` - 0
+- `APEX_VERSION_MINOR` - 1
+- `APEX_VERSION_PATCH` - 0
+- `APEX_VERSION_STRING` - "0.1.0"
+
+## Bump Version (increment)
+
+@run(make bump-${increment:patch})
+
+## Update Tests Badge
+
+Update the test badge in the src/_README.md
+
+```run Replace PASSING and TEST_COLOR comments in [%readme]
+#!/usr/bin/env ruby
+
+target = "[%readme:src/_README.md]"
+
+system("cmake --build build --target apex_test_runner &>/dev/null")
+pass_total = `build/apex_test_runner --badge`.strip.split("/").map(&:to_i)
+
+badge = "![Tests passing #{pass_total[0]}/#{pass_total[1]}](https://img.shields.io/badge/Tests-#{pass_total[0]}/#{pass_total[1]}-#{pass_total[0] == pass_total[1] ? "a5da78" : "f97373"})"
+File.write(target, File.read(target).gsub(/<!--TESTS_BADGE-->.*?<!--END TESTS_BADGE-->/m, "<!--TESTS_BADGE-->#{badge}<!--END TESTS_BADGE-->"))
+```
+
+## Deploy (increment)
+
+To create a release, bump the version in `VERSION`, commit, tag, and push:
+
+@before
+Are you sure your changelog Git entries are up to date?
+@end
+
+@include(Bump Version[${increment:patch}])
+
+```run Update changelog and create tag message
+#!/bin/bash
+
+VERSION=$(cat VERSION | tr -d '[:space:]')
+
+echo "v$VERSION" > tag_message.txt
+echo >> tag_message.txt
+changelog >> tag_message.txt
+changelog -u
+```
+
+@include(Update Tests Badge)
+@include(Update GitHub Readme)
+@include(Update Blog Project)
+
+```run Create and push release
+VERSION=$(cat VERSION | tr -d '[:space:]')
+
+git add VERSION
+git add CHANGELOG.md
+git add include/apex/apex.h
+git add CMakeLists.txt
+git commit -a -F tag_message.txt
+git tag "v$VERSION" -F tag_message.txt
+git push origin main
+git push origin "v$VERSION"
+rm tag_message.txt
+```
+
+The GitHub Actions workflow will automatically:
+
+- Build macOS universal binary (x86_64 + arm64)
+- Build Linux binaries (amd64 + arm64)
+- Generate SHA256 checksums
+- Create GitHub release with all artifacts
+
+```run Wait for CI to build and upload release artifacts
+#!/bin/bash
+# Wait for GitHub Actions to build and upload the tarball
+
+RED='\033[0;31m'
+YELLOW='\033[0;33m'
+CYAN='\033[0;36m'
+MAGENTA='\033[0;35m'
+GREEN='\033[0;32m'
+NC='\033[0m' # No Color (reset)
+B_WHITE='\033[1;37m'
+
+VERSION=$(cat VERSION | tr -d '[:space:]')
+TARBALL_URL="https://github.com/ApexMarkdown/apex/releases/download/v$VERSION/apex-$VERSION-macos-universal.tar.gz"
+
+echo -e "${YELLOW}Waiting for CI to build and upload release artifacts..."
+echo -e "${YELLOW}Checking for: ${B_WHITE}$TARBALL_URL"
+
+ATTEMPT_INTERVAL=10
+MAX_ATTEMPTS=60
+ATTEMPT=0
+
+while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
+	if curl -s -f -o /dev/null "$TARBALL_URL"; then
+		echo -e "${GREEN}✓ Release artifact is available!"
+		exit 0
+	fi
+
+	ATTEMPT=$((ATTEMPT + 1))
+  echo -ne "\r\033[K${YELLOW}Attempt ${B_WHITE}$ATTEMPT/${CYAN}$MAX_ATTEMPTS: ${YELLOW}Artifact not ready yet, waiting $ATTEMPT_INTERVAL seconds...${NC}"
+	sleep $ATTEMPT_INTERVAL
+done
+
+echo -e "${RED}⚠ Warning: Release artifact not available after $((MAX_ATTEMPTS * $MAX_INTERVAL)) seconds"
+echo -e "${B_WHITE}You may need to run 'Update Homebrew Formula' manually after CI completes"
+exit 0
+```
+
+@include(Publish the wiki)
+@include(Update Homebrew)
+
+@include?!(Release Node Module [${increment}])
+@include?!(Update and Deploy Ruby Gem)
+
+## Update and Deploy Ruby Gem
+
+- cd to the apex-ruby directory and run the deploy howzit task.
+
+```run Update Gem
+#!/usr/bin/bash
+
+cd ~/Desktop/Code/apex-ruby && howzit -r deploy
+```
+
+## Release Node module (increment:patch)
+
+The Node binding is published as `@apexmarkdown/apex` from the
+[`ApexMarkdown/apex-node`](https://github.com/ApexMarkdown/apex-node)
+repository. Its tag-triggered GitHub Actions workflow builds the platform
+packages first, uploads them as workflow artifacts, and only then runs the
+dependent npm publish job.
+
+Before the first release:
+
+- Create or join the `apexmarkdown` organization on npm. The
+  `@apexmarkdown/*` package scope belongs to that npm organization; the
+  GitHub organization does not create it automatically.
+- Enable npm 2FA for authorization and writes. An npm passkey/security key
+  satisfies the second-factor requirement for interactive publishing.
+- Log the local npm CLI in with `npm login` and confirm it with `npm whoami`.
+- Trusted publishing is configured on npm for the root and platform packages
+  against workflow `publish-prebuilds.yml` in `ApexMarkdown/apex-node`.
+
+Default increment is `patch`. Use `increment=current` only to tag the version
+already in `package.json` (first release / retry of an untagged bump). If that
+tag already exists, the task bumps patch automatically and continues. You can
+also pass `minor`, `major`, a prerelease increment, or an exact version. The
+task keeps every optional platform package pinned to the same version as the
+root package.
+
+```run Commit, tag, build, and publish Node module
+#!/bin/bash
+set -euo pipefail
+
+NODE_ROOT="$HOME/Desktop/Code/apex-node"
+REPO="ApexMarkdown/apex-node"
+WORKFLOW="publish-prebuilds.yml"
+INCREMENT="${increment:patch}"
+
+cd "$NODE_ROOT"
+
+if ! git diff --quiet || ! git diff --cached --quiet; then
+  echo "The apex-node working tree has uncommitted changes."
+  git status --short
+  exit 1
+fi
+
+git pull --ff-only origin main
+git submodule update --init --recursive
+
+sync_platform_versions() {
+  # Keep platform package requirements and package-lock metadata synchronized.
+  node <<'NODE'
+const fs = require("node:fs");
+
+const pkgPath = "package.json";
+const lockPath = "package-lock.json";
+const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+const lock = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+
+for (const name of Object.keys(pkg.optionalDependencies || {})) {
+  if (name.startsWith("@apexmarkdown/apex-")) {
+    pkg.optionalDependencies[name] = pkg.version;
+  }
+}
+
+lock.version = pkg.version;
+lock.packages[""].version = pkg.version;
+lock.packages[""].optionalDependencies = pkg.optionalDependencies;
+
+fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+fs.writeFileSync(lockPath, JSON.stringify(lock, null, 2) + "\n");
+NODE
+}
+
+case "$INCREMENT" in
+  current)
+    ;;
+  patch|minor|major|prepatch|preminor|premajor|prerelease)
+    npm version "$INCREMENT" --no-git-tag-version
+    ;;
+  [0-9]*)
+    npm version "$INCREMENT" --no-git-tag-version
+    ;;
+  *)
+    echo "Unsupported increment: $INCREMENT"
+    echo "Use current, patch, minor, major, a prerelease increment,"
+    echo "or an exact version."
+    exit 1
+    ;;
+esac
+
+sync_platform_versions
+
+VERSION=$(node -p "require('./package.json').version")
+TAG="v$VERSION"
+
+if git rev-parse "$TAG" >/dev/null 2>&1; then
+  echo "Tag $TAG already exists; bumping patch before tagging again."
+  npm version patch --no-git-tag-version
+  sync_platform_versions
+  VERSION=$(node -p "require('./package.json').version")
+  TAG="v$VERSION"
+  if git rev-parse "$TAG" >/dev/null 2>&1; then
+    echo "Tag $TAG still exists after patch bump."
+    exit 1
+  fi
+  echo "Continuing with $TAG"
+fi
+
+echo "Building and testing @apexmarkdown/apex $VERSION"
+npm install --no-audit --no-fund
+npm run build
+npm test
+npm run package:prebuild
+npm pack --dry-run
+
+if ! git diff --quiet -- package.json package-lock.json; then
+  git add package.json package-lock.json
+  git commit -m "$(cat <<EOF
+Release Node module v$VERSION.
+
+@changed **Node module release** preparing v$VERSION and its platform packages.
+
+EOF
+)"
+else
+  echo "Version files are unchanged; tagging the current commit."
+fi
+
+git tag -a "$TAG" -m "Release $TAG"
+COMMIT_SHA=$(git rev-parse HEAD)
+git push origin main
+git push origin "$TAG"
+
+echo "Waiting for the $WORKFLOW workflow to start..."
+RUN_ID=""
+for attempt in $(seq 1 30); do
+  RUN_ID=$(gh run list \
+    --repo "$REPO" \
+    --workflow "$WORKFLOW" \
+    --commit "$COMMIT_SHA" \
+    --limit 1 \
+    --json databaseId \
+    --jq '.[0].databaseId // empty')
+  if [ -n "$RUN_ID" ]; then
+    break
+  fi
+  sleep 5
+done
+
+if [ -z "$RUN_ID" ]; then
+  echo "Could not find the release workflow run for $TAG."
+  exit 1
+fi
+
+echo "Watching GitHub Actions run $RUN_ID..."
+gh run watch "$RUN_ID" --repo "$REPO" --exit-status
+
+echo "Generated artifacts:"
+gh api "repos/$REPO/actions/runs/$RUN_ID/artifacts" \
+  --jq '.artifacts[] | "  \(.name)"'
+
+PUBLISHED=$(npm view "@apexmarkdown/apex@$VERSION" version)
+if [ "$PUBLISHED" != "$VERSION" ]; then
+  echo "npm did not report @apexmarkdown/apex@$VERSION after the workflow completed."
+  exit 1
+fi
+
+echo "Published @apexmarkdown/apex@$PUBLISHED"
+```
+
+The CI matrix publishes all four platform packages: macOS arm64, macOS x64,
+Linux x64, and Linux arm64 (`ubuntu-24.04-arm`).
+
+The publish job uses **trusted publishing** (GitHub Actions OIDC) instead of
+`NPM_TOKEN`: it sets `permissions: id-token: write`, runs Node 24 with the
+latest npm, and has no `NODE_AUTH_TOKEN` settings. Each published package
+needs a trusted publisher configured on npmjs.com (Settings -> Trusted
+Publisher on the package page):
+
+- Organization or user: `ApexMarkdown`
+- Repository: `apex-node`
+- Workflow filename: `publish-prebuilds.yml` (filename only, no path)
+
+Configure it for `@apexmarkdown/apex` and every `@apexmarkdown/apex-*`
+platform package. `@apexmarkdown/apex-linux-arm64` was not published in
+0.1.0; after the next release creates it, add the same trusted publisher
+on that package page (or keep `NPM_TOKEN` available for that first
+create-only publish if OIDC rejects an unpublished name). All fields are
+case-sensitive and only checked at publish time. After a successful
+trusted-publish release for every package, delete the `NPM_TOKEN` repo
+secret and revoke the token on npm:
+
+```bash
+gh secret delete NPM_TOKEN --repo ApexMarkdown/apex-node
+```
+
+## Publish the wiki
+
+```run Commit and publish wiki changes
+#!/bin/bash
+# Update the wiki
+
+VERSION=$(cat VERSION | tr -d '[:space:]')
+cd $HOME/Desktop/Code/apex.wiki
+git ar
+git commit -a -m "v$VERSION update"
+git pull
+git push
+```
+
+## Update Homebrew
+
+After a release, update the Homebrew formula with the new version and binary SHA256:
+
+```run Update Homebrew formula
+#!/bin/bash
+set -e
+
+# Ensure we're in the apex directory (use $HOME instead of ~)
+APEX_DIR="$HOME/Desktop/Code/apex"
+cd "$APEX_DIR" || { echo "Error: Could not cd to $APEX_DIR"; exit 1; }
+
+# Debug: Show current directory and verify VERSION file exists
+echo "Current directory: $(pwd)"
+echo "VERSION file exists: $([ -f VERSION ] && echo 'yes' || echo 'no')"
+
+# Get current version - use absolute path to be safe
+VERSION_FILE="$APEX_DIR/VERSION"
+if [ ! -f "$VERSION_FILE" ]; then
+    echo "Error: VERSION file not found at $VERSION_FILE"
+    exit 1
+fi
+
+VERSION=$(cat "$VERSION_FILE" | tr -d '[:space:]')
+
+if [ -z "$VERSION" ]; then
+    echo "Error: VERSION file is empty or could not be read from $VERSION_FILE"
+    echo "Contents: '$(cat "$VERSION_FILE")'"
+    exit 1
+fi
+
+echo "Detected version: $VERSION"
+
+# Download the macOS universal tarball and compute its SHA256
+# NOTE: Use $VERSION (no braces) so Howzit doesn"t try to expand ${VERSION}"
+TARBALL_URL="https://github.com/ApexMarkdown/apex/releases/download/v$VERSION/apex-$VERSION-macos-universal.tar.gz"
+TARBALL_PATH="/tmp/apex-$VERSION-macos-universal.tar.gz"
+
+echo "Downloading tarball from $TARBALL_URL"
+curl -L -o "$TARBALL_PATH" "$TARBALL_URL"
+
+if [ ! -f "$TARBALL_PATH" ]; then
+    echo "Error: Failed to download tarball to $TARBALL_PATH"
+    exit 1
+fi
+
+echo "Raw shasum output:"
+SHASUM_OUTPUT=$(shasum -a 256 "$TARBALL_PATH")
+echo "$SHASUM_OUTPUT"
+
+# Extract just the SHA256 (first field) without using awk/curly braces (to avoid Howzit templating issues)
+SHA256=$(printf '%s\n' "$SHASUM_OUTPUT" | cut -d ' ' -f 1)
+
+if [ -z "$SHA256" ]; then
+    echo "Error: Failed to compute SHA256 for $TARBALL_PATH"
+    exit 1
+fi
+
+echo "Computed SHA256: $SHA256"
+
+# Verify Formula file exists
+FORMULA_FILE="$APEX_DIR/Formula/apex.rb"
+if [ ! -f "$FORMULA_FILE" ]; then
+    echo "Error: Formula file not found at $FORMULA_FILE"
+    exit 1
+fi
+
+# Debug: Verify variables are still set before using them
+echo "Before update - VERSION='$VERSION', SHA256='$SHA256'"
+
+# Create a temporary update script to ensure variables are available
+cat > /tmp/update_formula.rb << 'RUBY_SCRIPT'
+#!/usr/bin/env ruby
+version = ARGV[0]
+sha256 = ARGV[1]
+file = ARGV[2]
+
+content = File.read(file)
+content.gsub!(/^  version "[^"]*"/, "  version \"#{version}\"")
+content.gsub!(/^    sha256 "[^"]*"/, "    sha256 \"#{sha256}\"")
+
+File.write(file, content)
+RUBY_SCRIPT
+
+chmod +x /tmp/update_formula.rb
+/tmp/update_formula.rb "$VERSION" "$SHA256" "$FORMULA_FILE"
+rm /tmp/update_formula.rb
+
+# Debug: Verify variables are still set after update
+echo "After update - VERSION='$VERSION', SHA256='$SHA256'"
+
+echo "Updated Formula/apex.rb to version ${VERSION} with SHA256 ${SHA256}"
+cat "$FORMULA_FILE" | grep -E '(version "|sha256 ")'
+```
+
+```run Copy formula and push to homebrew-thelab
+#!/bin/bash
+
+# Copy formula to homebrew-thelab repo
+cp Formula/apex.rb ~/Desktop/Code/homebrew-thelab/Formula/
+
+cat ~/Desktop/Code/homebrew-thelab/Formula/apex.rb
+```
+
+```run Commit and push formula
+#!/bin/bash
+
+# Commit and push
+cd ~/Desktop/Code/homebrew-thelab
+git add Formula/apex.rb
+git commit -m "Update apex to $(grep 'version "' Formula/apex.rb | sed 's/.*version "\([^"]*\)".*/\1/')"
+git push origin main
+
+echo "Homebrew formula committed and pushed!"
+```
+
+## Deploy mk CLI (increment:patch, upload_site:false)
+
+Recommended distribution path: publish `mk.pkg` to a GitHub Release and have Homebrew install it from your tap as a **cask**. Homebrew formulae are best for source/tarball installs, while notarized PKGs map cleanly to casks and use the PKG SHA directly.
+
+If you still want `https://markedapp.com/download/mk.pkg`, keep that URL as a mirror by copying the same notarized file there after release.
+
+```run Build, sign, package, notarize, and staple mk.pkg
+#!/bin/bash
+set -euo pipefail
+
+MK_ROOT="$HOME/Desktop/Code/marked/mk"
+PBXPROJ="$MK_ROOT/mk.xcodeproj/project.pbxproj"
+DERIVED="$MK_ROOT/.build-mk-release"
+PKG_STAGE="$MK_ROOT/package"
+
+APP_SIGNING_IDENTITY="${APP_SIGNING_IDENTITY:-Developer ID Application: Brett Terpstra (47TRS7H4BH)}"
+INSTALLER_SIGNATURE="${INSTALLER_SIGNATURE:-Developer ID Installer: Brett Terpstra (47TRS7H4BH)}"
+NOTARY_PROFILE="${NOTARY_PROFILE:-Developer-notarytool}"
+PKG_IDENTIFIER="${PKG_IDENTIFIER:-com.brettterpstra.mk}"
+
+MK_VERSION=$(ruby -e 'f=ARGV[0]; s=File.read(f); m=s.match(/MARKETING_VERSION = ([^;]+);/); abort("Could not parse MARKETING_VERSION") unless m; puts m[1].strip' "$PBXPROJ")
+PKG_PATH="$MK_ROOT/mk-$MK_VERSION.pkg"
+
+echo "Building mk v$MK_VERSION"
+rm -rf "$DERIVED" "$PKG_STAGE" "$PKG_PATH"
+
+xcodebuild \
+  -project "$MK_ROOT/mk.xcodeproj" \
+  -scheme mk \
+  -configuration Release \
+  -derivedDataPath "$DERIVED" \
+  ARCHS="arm64 x86_64" \
+  ONLY_ACTIVE_ARCH=NO \
+  build
+
+BIN_PATH="$DERIVED/Build/Products/Release/mk"
+if [ ! -x "$BIN_PATH" ]; then
+  echo "Could not find built mk binary at $BIN_PATH"
+  exit 1
+fi
+
+codesign --force --sign "$APP_SIGNING_IDENTITY" --timestamp --options runtime "$BIN_PATH"
+codesign --verify -vvvv "$BIN_PATH"
+
+mkdir -p "$PKG_STAGE/usr/local/bin"
+cp "$BIN_PATH" "$PKG_STAGE/usr/local/bin/mk"
+
+pkgbuild \
+  --root "$PKG_STAGE" \
+  --identifier "$PKG_IDENTIFIER" \
+  --version "$MK_VERSION" \
+  --sign "$INSTALLER_SIGNATURE" \
+  "$PKG_PATH"
+
+echo "Submitting for notarization..."
+xcrun notarytool submit "$PKG_PATH" --keychain-profile "$NOTARY_PROFILE" --wait
+xcrun stapler staple "$PKG_PATH"
+xcrun stapler validate "$PKG_PATH"
+
+SHA256=$(shasum -a 256 "$PKG_PATH" | cut -d ' ' -f 1)
+echo "$SHA256" > "$MK_ROOT/mk-$MK_VERSION.pkg.sha256"
+
+echo "Built package: $PKG_PATH"
+echo "SHA256: $SHA256"
+```
+
+```run Publish mk.pkg to GitHub Release (recommended canonical host)
+#!/bin/bash
+set -euo pipefail
+
+MK_ROOT="$HOME/Desktop/Code/marked/mk"
+PBXPROJ="$MK_ROOT/mk.xcodeproj/project.pbxproj"
+MK_RELEASE_REPO="${MK_RELEASE_REPO:-ttscoff/mk}"
+MK_VERSION=$(ruby -e 'f=ARGV[0]; s=File.read(f); m=s.match(/MARKETING_VERSION = ([^;]+);/); abort("Could not parse MARKETING_VERSION") unless m; puts m[1].strip' "$PBXPROJ")
+PKG_PATH="$MK_ROOT/mk-$MK_VERSION.pkg"
+
+if [ ! -f "$PKG_PATH" ]; then
+  echo "Missing package: $PKG_PATH"
+  echo "Run 'Build, sign, package, notarize, and staple mk.pkg' first."
+  exit 1
+fi
+
+if gh release view "v$MK_VERSION" --repo "$MK_RELEASE_REPO" >/dev/null 2>&1; then
+  gh release upload "v$MK_VERSION" "$PKG_PATH" --repo "$MK_RELEASE_REPO" --clobber
+else
+  gh release create "v$MK_VERSION" "$PKG_PATH" \
+    --repo "$MK_RELEASE_REPO" \
+    --title "mk v$MK_VERSION" \
+    --notes "Notarized mk CLI installer package."
+fi
+
+echo "Release asset URL:"
+echo "https://github.com/$MK_RELEASE_REPO/releases/download/v$MK_VERSION/mk-$MK_VERSION.pkg"
+```
+
+```run Optionally mirror mk.pkg to markedapp.com/download
+#!/bin/bash
+set -euo pipefail
+
+MK_ROOT="$HOME/Desktop/Code/marked/mk"
+PBXPROJ="$MK_ROOT/mk.xcodeproj/project.pbxproj"
+MARKEDAPP_SSH_TARGET="${MARKEDAPP_SSH_TARGET:-markedapp@your-server:/var/www/markedapp.com/download/mk.pkg}"
+MK_VERSION=$(ruby -e 'f=ARGV[0]; s=File.read(f); m=s.match(/MARKETING_VERSION = ([^;]+);/); abort("Could not parse MARKETING_VERSION") unless m; puts m[1].strip' "$PBXPROJ")
+PKG_PATH="$MK_ROOT/mk-$MK_VERSION.pkg"
+
+if [ ! -f "$PKG_PATH" ]; then
+  echo "Missing package: $PKG_PATH"
+  exit 1
+fi
+
+scp "$PKG_PATH" "$MARKEDAPP_SSH_TARGET"
+echo "Uploaded to $MARKEDAPP_SSH_TARGET"
+```
+
+```run Update Homebrew tap entry for mk.pkg (cask)
+#!/bin/bash
+set -euo pipefail
+
+MK_ROOT="$HOME/Desktop/Code/marked/mk"
+PBXPROJ="$MK_ROOT/mk.xcodeproj/project.pbxproj"
+TAP_ROOT="$HOME/Desktop/Code/homebrew-thelab"
+MK_RELEASE_REPO="${MK_RELEASE_REPO:-ttscoff/mk}"
+MK_VERSION=$(ruby -e 'f=ARGV[0]; s=File.read(f); m=s.match(/MARKETING_VERSION = ([^;]+);/); abort("Could not parse MARKETING_VERSION") unless m; puts m[1].strip' "$PBXPROJ")
+PKG_PATH="$MK_ROOT/mk-$MK_VERSION.pkg"
+SHA256=$(shasum -a 256 "$PKG_PATH" | cut -d ' ' -f 1)
+
+mkdir -p "$TAP_ROOT/Casks"
+CASK_FILE="$TAP_ROOT/Casks/mk.rb"
+
+cat > "$CASK_FILE" <<EOF
+cask "mk" do
+  version "$MK_VERSION"
+  sha256 "$SHA256"
+
+  url "https://github.com/$MK_RELEASE_REPO/releases/download/v#{version}/mk-#{version}.pkg"
+  name "mk"
+  desc "Marked command line utility"
+  homepage "https://markedapp.com"
+
+  pkg "mk-#{version}.pkg"
+  uninstall pkgutil: "com.brettterpstra.mk"
+end
+EOF
+
+cd "$TAP_ROOT"
+git add "$CASK_FILE"
+git commit -m "Add/update mk cask v$MK_VERSION"
+git push origin main
+
+echo "Updated $CASK_FILE with sha256 $SHA256"
+```
+
+If you decide to keep Homebrew as a **formula** instead of a cask, publish a tarball containing only the `mk` binary and use that tarball SHA in `Formula/mk.rb`. A formula that downloads a PKG is possible but not recommended.
+
+## AST filters (Pandoc-style)
+
+Apex now supports **AST-level filters** similar to Pandoc's JSON filters
+([Pandoc filters](https://pandoc.org/filters.html#summary)).
+
+- Pipeline:
+  - Markdown → cmark-gfm AST → **Pandoc-compatible JSON AST**
+  - JSON AST → external filters → JSON AST
+  - JSON AST → cmark-gfm AST → HTML
+- Filters are ordinary executables that:
+  - Read a Pandoc JSON AST from **stdin**
+  - Write a (possibly transformed) JSON AST to **stdout**
+
+### CLI flags
+
+- `--filter NAME`:
+  - Runs a single filter from `~/.config/apex/filters/NAME`
+  - `NAME` should be an executable (any language) that implements the Pandoc
+    JSON filter contract.
+- `--filters`:
+  - Runs all executable files in `~/.config/apex/filters`, sorted by filename.
+- `--no-strict-filters`:
+  - By default, Apex **aborts** if a filter exits non-zero or returns invalid JSON.
+  - With this flag, Apex logs a warning and **skips** the failing filter instead.
+
+### Ruby bindings
+
+`Apex::Document.markdown_to_html` accepts two new options:
+
+- `ast_filters: [ "cmd1", "cmd2" ]`
+- `ast_filter_strict: false` (optional, defaults to strict)
+
+Example:
+
+```ruby
+html = Apex::Document.markdown_to_html(
+  markdown,
+  mode: :unified,
+  ast_filters: ["~/.config/apex/filters/behead"],
+  ast_filter_strict: true
+)
+```
+
+### Example filters
+
+Python (using `pandocfilters`) – convert level 2+ headings to paragraphs
+with emphasized text:
+
+```python
+#!/usr/bin/env python3
+
+from pandocfilters import toJSONFilter, Emph, Para
+
+def behead(key, value, fmt, meta):
+    if key == "Header" and value[0] >= 2:
+        return Para([Emph(value[2])])
+
+if __name__ == "__main__":
+    toJSONFilter(behead)
+```
+
+Install as `~/.config/apex/filters/behead` (make it executable), then:
+
+```bash
+apex --filter behead input.md > output.html
+```
+
+Ruby filter – uppercase all words in plain paragraphs:
+
+```ruby
+#!/usr/bin/env ruby
+
+require "json"
+
+doc = JSON.parse($stdin.read)
+
+doc["blocks"].each do |blk|
+  next unless blk["t"] == "Para"
+  blk["c"].each do |inline|
+    next unless inline["t"] == "Str"
+    inline["c"] = inline["c"].upcase
+  end
+end
+
+puts JSON.dump(doc)
+```
+
+Save as `~/.config/apex/filters/upper_para` (and `chmod +x`), then:
+
+```bash
+apex --filter upper_para input.md > output.html
+```
+
+## Cursor Commands (command)
+
+
+/buildnotes
+: Add sections to this file
+
+/changelog
+: Generate a commit_message.txt with @tags and notes about staged and unstaged changes.
+
+/commit
+: Run `git commit -a -F commit_message.txt`
+
+/docs
+: Update the Wiki documentation (../apex.wiki)
+
+/prefix_commands
+: Instruct Cursor to run appropriate commands with `mise x`, and prefix built-ins with `command`.
+
+/readme
+: Update src/_README.md
+
+@run(cursor-agent --output-format text --print .cursor/commands/${command:changelog}.md && afplay /System/Library/Sounds/Hero.aiff)