apex-ruby 1.0.6

data/ext/apex_ext/apex_src/docs/WIKI_LINKS_ISSUE.md

@@ -0,0 +1,91 @@
+# Wiki Links Implementation Issue
+
+## Problem
+
+Wiki links (`[[Page]]`) are not being detected because:
+
+1. The `[` character is already registered by cmark-gfm's
+
+   standard link parser
+
+2. When `[` is encountered, the standard link parser gets
+
+   priority
+
+3. Our extension's match function is either not called, or
+
+   is called after the standard link parser has already
+   consumed the `[`
+
+## Attempted Solutions
+
+### Attempt 1: Register as inline extension
+- Added `[` as special character
+- Set match function
+- **Result**: Not called or called too late
+
+### Attempt 2: Check for `[[` in match function
+- Added check for double `[[` at start of match function
+- **Result**: Still not working - match function may not be
+
+  getting called at all
+
+## Root Cause
+
+cmark-gfm processes inline elements in a specific order:
+
+1. Built-in syntax (links, emphasis) is handled first
+2. Extension syntax is handled after
+3. Since `[` triggers link processing, standard markdown
+
+   link syntax wins
+
+## Possible Solutions
+
+### Option A: Preprocessing
+Convert `[[...]]` to temporary markers before parsing, then
+convert back in HTML
+
+```
+[[Page]] → ⟦⟦Page⟧⟧  (preprocessing)
+Parse with cmark-gfm
+⟦⟦Page⟧⟧ → <a href="Page">Page</a>  (postprocessing)
+
+```
+
+### Option B: Postprocessing
+Let markdown parse normally, then walk AST and convert text
+nodes containing `[[...]]`
+
+### Option C: Custom inline parser hook (if available)
+Hook into inline parsing at a lower level to intercept `[[`
+before link parsing
+
+### Option D: Different syntax
+Use a character that doesn't conflict: `{{Page}}` or
+`<<Page>>`
+
+## Recommendation
+
+**Use postprocessing (Option B)** - Most reliable approach:
+
+1. Parse markdown normally with cmark-gfm
+2. Walk the AST looking for TEXT nodes
+3. Find `[[...]]` patterns in text
+4. Split text node and insert LINK nodes
+
+This is how Marked currently handles wiki links and it works
+reliably.
+
+## Implementation Plan
+
+1. Remove the inline match approach
+
+Add `apex_process_wiki_links(cmark_node *document)` function
+
+3. Walk AST, find TEXT nodes
+4. Use regex or manual parsing to find `[[...]]`
+5. Split text, insert link nodes
+
+Call this after `cmark_parser_finish()` but before rendering
+

data/ext/apex_ext/apex_src/documentation/README.md

@@ -0,0 +1,160 @@
+# Apex Documentation Generators
+
+This directory contains scripts to generate documentation from the Apex wiki.
+
+## Scripts
+
+### `generate_docset.rb`
+
+Generates Dash docsets for Apex documentation.
+
+**Usage:**
+```bash
+./generate_docset.rb [single|multi]
+```
+
+- `single` - Generate single-page CLI options docset (ApexCLI.docset)
+- `multi` - Generate multi-page docset from wiki files (Apex.docset, default)
+
+**Output:**
+- Docsets are generated in `docsets/` directory
+- The script automatically clones the wiki from GitHub and cleans up after running
+
+### `generate_single_html.rb`
+
+Generates a single HTML file with all wiki pages, using JavaScript to show/hide pages.
+
+**Usage:**
+```bash
+./generate_single_html.rb
+```
+
+**Output:**
+- HTML file is generated in `html/apex-docs.html`
+- The script automatically clones the wiki from GitHub and cleans up after running
+
+### `generate_app_docs.rb`
+
+Generates app-focused documentation from pre-transformed Markdown files. This script reads from `app-transformed/` and generates a single HTML file suitable for embedding in apps like Marked.app.
+
+**Usage:**
+```bash
+./generate_app_docs.rb
+```
+
+**Output:**
+- HTML file is generated in `html/apex-app-docs.html`
+- Settings table is generated in `app-settings-table.md`
+- Uses pre-transformed files from `app-transformed/` directory
+
+**Note:** This script requires pre-transformed Markdown files. See "AI Transformation Workflow" below for how to create them.
+
+### `generate_app_docs_ai.rb`
+
+Uses AI (via cursor-agent or similar) to transform CLI-focused documentation into app-focused documentation. This script can automatically transform wiki pages by replacing CLI references with app Settings references.
+
+**Usage:**
+```bash
+./generate_app_docs_ai.rb
+```
+
+**Requirements:**
+- `cursor-agent` or similar AI agent tool
+- `transform_for_app.md` file (copy from `transform_for_app.example.md`)
+
+**Output:**
+- Transformed Markdown files in `app-transformed/` directory
+- HTML file is generated in `html/apex-app-docs.html`
+- Settings table is generated in `app-settings-table.md`
+
+**Note:** This script requires manual setup. See "AI Transformation Workflow" below.
+
+## Requirements
+
+- Ruby
+- Apex binary (in PATH or in `../build-release/apex`)
+- `sqlite3` gem (for multi-page docset): `gem install sqlite3`
+- `mmd2cheatset` (for single-page docset): Should be at `~/Desktop/Code/mmd2cheatset/mmd2cheatset.rb`
+- Git (for cloning the wiki)
+
+## Directory Structure
+
+```
+documentation/
+├── generate_docset.rb           # Dash docset generator
+├── generate_single_html.rb      # Single HTML file generator
+├── generate_app_docs.rb         # App docs generator (uses pre-transformed files)
+├── generate_app_docs_ai.rb      # AI-powered app docs transformer
+├── transform_for_app.example.md # Example transformation instructions
+├── docsets/                     # Generated docsets (gitignored)
+│   ├── Apex.docset
+│   └── ApexCLI.docset
+├── html/                        # Generated HTML files (gitignored)
+│   ├── apex-docs.html
+│   └── apex-app-docs.html
+├── app-transformed/             # Transformed Markdown files (gitignored)
+│   ├── Syntax.md
+│   ├── Modes.md
+│   ├── Plugins.md
+│   └── ...
+└── app-settings-table.md        # Generated settings reference table
+```
+
+## How It Works
+
+### Standard Documentation Generation
+
+The standard scripts (`generate_docset.rb` and `generate_single_html.rb`):
+1. Clone the wiki from `https://github.com/ApexMarkdown/apex.wiki.git` into `apex.wiki/`
+2. Process the wiki files
+3. Generate the output
+4. Clean up by removing the cloned wiki directory
+
+This ensures the latest version of the wiki is always used and no local wiki clone is required.
+
+### AI Transformation Workflow
+
+The app-focused documentation uses a hybrid approach:
+
+1. **Manual Transformation (Recommended)**
+   - Copy `transform_for_app.example.md` to `transform_for_app.md`
+   - Edit `transform_for_app.md` to match your app's settings structure
+   - Manually transform wiki pages using the instructions in `transform_for_app.md`
+   - Save transformed files to `app-transformed/` directory
+   - Run `generate_app_docs.rb` to generate the HTML
+
+2. **AI-Powered Transformation (Experimental)**
+   - Copy `transform_for_app.example.md` to `transform_for_app.md`
+   - Edit `transform_for_app.md` if needed for your app
+   - Ensure `cursor-agent` or similar AI tool is available
+   - Run `generate_app_docs_ai.rb` to automatically transform files
+   - Review and edit the generated files in `app-transformed/` as needed
+   - Run `generate_app_docs.rb` to generate the HTML
+
+**Transformation Instructions:**
+
+The `transform_for_app.example.md` file contains comprehensive instructions for transforming CLI-focused documentation to app-focused documentation. Key transformations include:
+
+- Replace CLI flags (`--flag`) with Settings references (`Settings->Category->Setting Name`)
+- Remove command-line examples (code blocks showing `apex` commands)
+- Remove links to "Command Line Options" page
+- Add app-specific instructions (e.g., "Marked will automatically detect...")
+- Page-specific transformations for Multi-File-Documents, Plugins, Modes, etc.
+
+**Example:**
+
+**Before (CLI-focused):**
+> Use the `--plugins` flag to enable plugins:
+>
+> ```bash
+> apex document.md --plugins
+> ```
+
+**After (App-focused):**
+> Enable plugins by checking **Settings->Processor->Include Plugins**.
+
+**Important Notes:**
+
+- The `app-transformed/` directory and `transform_for_app.md` are gitignored
+- This allows you to maintain app-specific documentation without committing it to the public repo
+- The example file (`transform_for_app.example.md`) is tracked in git as a template

data/ext/apex_ext/apex_src/documentation/docsets/Apex Command Line Options.cheatsheet.txt

@@ -0,0 +1,365 @@
+cheatsheet do
+	title 'Apex Command Line Options'
+	docset_file_name 'ApexCLI'
+	keyword 'apex'
+	introduction <<-'END'
+Complete reference for all Apex command-line flags and options.
+END
+	category do
+		id 'Command Line Options'
+		entry do
+			name 'Help'
+			command '-h'
+			command '--help'
+
+			notes %(Display help message and exit)
+		end
+		entry do
+			name 'Version'
+			command '-v'
+			command '--version'
+
+			notes %(Display version information and exit)
+		end
+		entry do
+			name 'Progress'
+			command '--[no-]progress'
+
+			notes %(Show progress indicator during processing)
+		end
+		entry do
+			name 'Combine'
+			command '--combine'
+
+			notes %(Concatenate Markdown files into a single stream)
+		end
+		entry do
+			name 'MMD Merge'
+			command '--mmd-merge'
+
+			notes %(Merge files from MultiMarkdown index files)
+		end
+		entry do
+			name 'Mode'
+			command '-m'
+			command '--mode MODE'
+
+			notes %(Set processor mode (commonmark, gfm, mmd, kramdown, unified))
+		end
+		entry do
+			name 'Output'
+			command '-o'
+			command '--output FILE'
+
+			notes %(Write output to a file instead of stdout)
+		end
+		entry do
+			name 'Standalone'
+			command '-s'
+			command '--standalone'
+
+			notes %(Generate complete HTML document)
+		end
+		entry do
+			name 'Style'
+			command '--style FILE'
+			command '--css FILE'
+
+			notes %(Link to a CSS file in document head)
+		end
+		entry do
+			name 'Embed CSS'
+			command '--embed-css'
+
+			notes %(Embed CSS file contents into style tag)
+		end
+		entry do
+			name 'Script'
+			command '--script VALUE'
+
+			notes %(Inject script tags (mermaid, mathjax, katex, etc.))
+		end
+		entry do
+			name 'Title'
+			command '--title TITLE'
+
+			notes %(Set the document title)
+		end
+		entry do
+			name 'Pretty'
+			command '--pretty'
+
+			notes %(Pretty-print HTML with indentation)
+		end
+		entry do
+			name 'ARIA'
+			command '--aria'
+
+			notes %(Add ARIA labels and accessibility attributes)
+		end
+		entry do
+			name 'Plugins'
+			command '--plugins'
+			command '--no-plugins'
+
+			notes %(Enable or disable plugin processing)
+		end
+		entry do
+			name 'List Plugins'
+			command '--list-plugins'
+
+			notes %(List installed and available plugins)
+		end
+		entry do
+			name 'Install Plugin'
+			command '--install-plugin ID-or-URL'
+
+			notes %(Install a plugin by ID or URL)
+		end
+		entry do
+			name 'Uninstall Plugin'
+			command '--uninstall-plugin ID'
+
+			notes %(Uninstall a locally installed plugin)
+		end
+		entry do
+			name 'ID Format'
+			command '--id-format FORMAT'
+
+			notes %(Set header ID generation format (gfm, mmd, kramdown))
+		end
+		entry do
+			name 'No IDs'
+			command '--no-ids'
+
+			notes %(Disable automatic header ID generation)
+		end
+		entry do
+			name 'Header Anchors'
+			command '--header-anchors'
+
+			notes %(Generate anchor tags instead of id attributes)
+		end
+		entry do
+			name 'Relaxed Tables'
+			command '--relaxed-tables'
+
+			notes %(Enable relaxed table parsing)
+		end
+		entry do
+			name 'No Relaxed Tables'
+			command '--no-relaxed-tables'
+
+			notes %(Disable relaxed table parsing)
+		end
+		entry do
+			name 'Captions'
+			command '--captions POSITION'
+
+			notes %(Control table caption position (above, below))
+		end
+		entry do
+			name 'No Tables'
+			command '--no-tables'
+
+			notes %(Disable table support entirely)
+		end
+		entry do
+			name 'Alpha Lists'
+			command '--[no-]alpha-lists'
+
+			notes %(Control alphabetic list markers (a., b., c.))
+		end
+		entry do
+			name 'Mixed Lists'
+			command '--[no-]mixed-lists'
+
+			notes %(Control mixed list marker types)
+		end
+		entry do
+			name 'No Footnotes'
+			command '--no-footnotes'
+
+			notes %(Disable footnote support)
+		end
+		entry do
+			name 'No Smart'
+			command '--no-smart'
+
+			notes %(Disable smart typography)
+		end
+		entry do
+			name 'No Math'
+			command '--no-math'
+
+			notes %(Disable math support)
+		end
+		entry do
+			name 'Autolink'
+			command '--[no-]autolink'
+
+			notes %(Control automatic linking of URLs and email addresses)
+		end
+		entry do
+			name 'Obfuscate Emails'
+			command '--obfuscate-emails'
+
+			notes %(Obfuscate email links by hex-encoding)
+		end
+		entry do
+			name 'Includes'
+			command '--includes'
+			command '--no-includes'
+
+			notes %(Enable or disable file inclusion features)
+		end
+		entry do
+			name 'Embed Images'
+			command '--embed-images'
+
+			notes %(Embed local images as base64 data URLs)
+		end
+		entry do
+			name 'Base Dir'
+			command '--base-dir DIR'
+
+			notes %(Set base directory for resolving relative paths)
+		end
+		entry do
+			name 'Transforms'
+			command '--[no-]transforms'
+
+			notes %(Control metadata variable transforms)
+		end
+		entry do
+			name 'Meta File'
+			command '--meta-file FILE'
+
+			notes %(Load metadata from external file)
+		end
+		entry do
+			name 'Meta'
+			command '--meta KEY=VALUE'
+
+			notes %(Set metadata from command line)
+		end
+		entry do
+			name 'Bibliography'
+			command '--bibliography FILE'
+
+			notes %(Specify bibliography file (BibTeX, CSL JSON, CSL YAML))
+		end
+		entry do
+			name 'CSL'
+			command '--csl FILE'
+
+			notes %(Specify Citation Style Language file)
+		end
+		entry do
+			name 'No Bibliography'
+			command '--no-bibliography'
+
+			notes %(Suppress bibliography output)
+		end
+		entry do
+			name 'Link Citations'
+			command '--link-citations'
+
+			notes %(Link citations to bibliography entries)
+		end
+		entry do
+			name 'Show Tooltips'
+			command '--show-tooltips'
+
+			notes %(Enable tooltips on citations when hovering)
+		end
+		entry do
+			name 'Indices'
+			command '--indices'
+
+			notes %(Enable index processing)
+		end
+		entry do
+			name 'No Indices'
+			command '--no-indices'
+
+			notes %(Disable index processing entirely)
+		end
+		entry do
+			name 'No Index'
+			command '--no-index'
+
+			notes %(Suppress index generation while creating markers)
+		end
+		entry do
+			name 'Hardbreaks'
+			command '--hardbreaks'
+
+			notes %(Treat newlines as hard breaks (GFM style))
+		end
+		entry do
+			name 'Sup Sub'
+			command '--[no-]sup-sub'
+
+			notes %(Control MultiMarkdown-style superscript and subscript)
+		end
+		entry do
+			name 'Divs'
+			command '--[no-]divs'
+
+			notes %(Control Pandoc fenced divs syntax)
+		end
+		entry do
+			name 'Spans'
+			command '--[no-]spans'
+
+			notes %(Control Pandoc-style bracketed spans)
+		end
+		entry do
+			name 'Emoji Autocorrect'
+			command '--[no-]emoji-autocorrect'
+
+			notes %(Control emoji name autocorrect)
+		end
+		entry do
+			name 'Unsafe'
+			command '--[no-]unsafe'
+
+			notes %(Control whether raw HTML is allowed)
+		end
+		entry do
+			name 'Wikilinks'
+			command '--[no-]wikilinks'
+
+			notes %(Control wiki link syntax)
+		end
+		entry do
+			name 'Wikilink Space'
+			command '--wikilink-space MODE'
+
+			notes %(Control how spaces in wiki links are handled)
+		end
+		entry do
+			name 'Wikilink Extension'
+			command '--wikilink-extension EXT'
+
+			notes %(Add file extension to wiki link URLs)
+		end
+		entry do
+			name 'Accept'
+			command '--accept'
+
+			notes %(Accept all Critic Markup changes)
+		end
+		entry do
+			name 'Reject'
+			command '--reject'
+
+			notes %(Reject all Critic Markup changes)
+		end
+	end
+
+	notes <<-'END'
+For complete documentation, see the Apex wiki at https://github.com/ApexMarkdown/apex/wiki
+END
+end

data/ext/apex_ext/apex_src/documentation/docsets/Apex.docset/Contents/Info.plist

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleIdentifier</key>
+  <string>apex</string>
+  <key>CFBundleName</key>
+  <string>Apex</string>
+  <key>DocSetPlatformFamily</key>
+  <string>apex</string>
+  <key>isDashDocset</key>
+  <true/>
+  <key>dashIndexFilePath</key>
+  <string>Home.html</string>
+  <key>DashDocSetFamily</key>
+  <string>dashtoc</string>
+  <key>DashDocSetPluginKeyword</key>
+  <string>apex</string>
+  <key>DashDocSetFallbackURL</key>
+  <string>Home.html</string>
+  <key>DashDocSetDeclaredInStyle</key>
+  <string>originalName</string>
+</dict>
+</plist>