apex-ruby 1.0.17 → 1.0.20

data/ext/apex_ext/apex_src/documentation/app-transformed/Metadata-Transforms.md

@@ -0,0 +1,461 @@
+# Metadata Transforms
+
+Metadata transforms allow you to modify metadata values using the `[%key:transform]` syntax. Transforms can be chained together, and many accept optional parameters.
+
+## Metadata Sources
+
+Metadata can come from three sources (merged in priority order):
+
+1. **Document**: Metadata embedded in the document (YAML, MMD, or Pandoc format)
+2. **External file**: Select a metadata file in **Settings->Processor->Metadata File**, or specify a file in document metadata
+3. **Document metadata**: Metadata specified in the document's front matter
+
+You can create reusable metadata files for common settings like language and quotes language. This is especially useful for maintaining consistent settings across multiple documents.
+
+## Basic Usage
+
+The basic syntax is `[%key:transform]` where `key` is a metadata key and `transform` is one of the available transforms:
+
+```markdown
+---
+title: hello world
+---
+
+# [%title:upper]
+<!-- Outputs: # HELLO WORLD -->
+```
+
+Transforms can be chained using colons:
+
+```markdown
+---
+title: hello world
+---
+
+# [%title:title:split( ):first]
+<!-- Outputs: # Hello -->
+```
+
+## Enabling Transforms
+
+Metadata transforms are **enabled by default in unified mode**. For other modes, enable them in **Settings->Processor->Metadata Transforms**. You can disable transforms (even in unified mode) by unchecking this setting.
+
+## Case Transforms
+
+### `upper`
+Converts the value to uppercase.
+
+```markdown
+---
+title: hello world
+---
+
+[%title:upper]
+<!-- Outputs: HELLO WORLD -->
+```
+
+### `lower`
+Converts the value to lowercase.
+
+```markdown
+---
+title: HELLO WORLD
+---
+
+[%title:lower]
+<!-- Outputs: hello world -->
+```
+
+### `title`
+Converts the value to title case (capitalizes first letter of each word).
+
+```markdown
+---
+title: hello world
+---
+
+[%title:title]
+<!-- Outputs: Hello World -->
+```
+
+### `capitalize`
+Capitalizes only the first letter of the value.
+
+```markdown
+---
+title: hello world
+---
+
+[%title:capitalize]
+<!-- Outputs: Hello world -->
+```
+
+## String Manipulation
+
+### `trim`
+Removes leading and trailing whitespace.
+
+```markdown
+---
+title: "  hello world  "
+---
+
+[%title:trim]
+<!-- Outputs: hello world -->
+```
+
+### `slug` / `slugify`
+Converts the value to a URL-friendly slug (lowercase, spaces and special characters replaced with hyphens).
+
+```markdown
+---
+title: My Great Post!
+---
+
+[%title:slug]
+<!-- Outputs: my-great-post -->
+```
+
+### `replace(OLD,NEW)` / `replace(regex:PATTERN,REPLACEMENT)`
+Replaces occurrences of `OLD` with `NEW`. Supports both simple string replacement and regex patterns.
+
+```markdown
+---
+url: http://example.com
+---
+
+[%url:replace(http:,https:)]
+<!-- Outputs: https://example.com -->
+```
+
+**Regex replacement:**
+```markdown
+---
+text: Hello 123 World
+---
+
+[%text:replace(regex:[0-9]+,N)]
+<!-- Outputs: Hello N World -->
+```
+
+### `substring(START,END)` / `substr(START,END)`
+Extracts a substring. Supports negative indices (from end).
+
+```markdown
+---
+title: Hello World
+---
+
+[%title:substr(0,5)]
+<!-- Outputs: Hello -->
+
+[%title:substr(-5)]
+<!-- Outputs: World (last 5 characters) -->
+```
+
+### `truncate(LENGTH,SUFFIX)`
+Truncates the value to the specified length, optionally appending a suffix.
+
+```markdown
+---
+title: This is a very long title
+---
+
+[%title:truncate(15,...)]
+<!-- Outputs: This is a very... -->
+```
+
+### `reverse`
+Reverses the order of characters in the value.
+
+```markdown
+---
+text: Hello
+---
+
+[%text:reverse]
+<!-- Outputs: olleH -->
+```
+
+## Array Transforms
+
+### `split(DELIMITER)`
+Splits a string into an array using the specified delimiter (default: space).
+
+```markdown
+---
+tags: tag1,tag2,tag3
+---
+
+[%tags:split(,)]
+<!-- Outputs: tag1 (first element as representation) -->
+<!-- Use with :first, :last, :slice, or :join to work with the array -->
+```
+
+### `join(DELIMITER)`
+Joins an array into a string using the specified delimiter.
+
+```markdown
+---
+tags: tag1,tag2,tag3
+---
+
+[%tags:split(,):join( | )]
+<!-- Outputs: tag1 | tag2 | tag3 -->
+```
+
+### `first`
+Returns the first element of an array.
+
+```markdown
+---
+tags: tag1,tag2,tag3
+---
+
+[%tags:split(,):first]
+<!-- Outputs: tag1 -->
+```
+
+### `last`
+Returns the last element of an array.
+
+```markdown
+---
+tags: tag1,tag2,tag3
+---
+
+[%tags:split(,):last]
+<!-- Outputs: tag3 -->
+```
+
+### `slice(START,LENGTH)`
+Extracts a slice from an array. If applied to a non-array value, splits the string into individual characters.
+
+```markdown
+---
+tags: tag1,tag2,tag3
+---
+
+[%tags:split(,):slice(0,2):join(,)]
+<!-- Outputs: tag1,tag2 -->
+
+---
+text: Hello
+---
+
+[%text:slice(0,5)]
+<!-- Outputs: Hello (characters 0-5) -->
+```
+
+## Utility Transforms
+
+### `default(VALUE)`
+Returns the specified default value if the metadata value is empty.
+
+```markdown
+---
+desc: ""
+---
+
+[%desc:default(No description)]
+<!-- Outputs: No description -->
+```
+
+### `escape` / `html_escape`
+Escapes HTML special characters (`&`, `<`, `>`, `"`, `'`).
+
+```markdown
+---
+title: A & B
+---
+
+[%title:html_escape]
+<!-- Outputs: A &amp; B -->
+```
+
+### `basename`
+Extracts the filename from a path.
+
+```markdown
+---
+image: /path/to/image.jpg
+---
+
+[%image:basename]
+<!-- Outputs: image.jpg -->
+```
+
+### `urlencode`
+URL-encodes the value.
+
+```markdown
+---
+search: hello world
+---
+
+[%search:urlencode]
+<!-- Outputs: hello%20world -->
+```
+
+### `urldecode`
+URL-decodes the value.
+
+```markdown
+---
+search: hello%20world
+---
+
+[%search:urldecode]
+<!-- Outputs: hello world -->
+```
+
+### `prefix(VALUE)`
+Adds a prefix to the value.
+
+```markdown
+---
+url: example.com
+---
+
+[%url:prefix(https://)]
+<!-- Outputs: https://example.com -->
+```
+
+### `suffix(VALUE)`
+Adds a suffix to the value.
+
+```markdown
+---
+title: Hello
+---
+
+[%title:suffix(!)]
+<!-- Outputs: Hello! -->
+```
+
+### `remove(STRING)`
+Removes all occurrences of the specified string.
+
+```markdown
+---
+title: Hello'World
+---
+
+[%title:remove(')]
+<!-- Outputs: HelloWorld -->
+```
+
+### `repeat(COUNT)`
+Repeats the value the specified number of times.
+
+```markdown
+---
+sep: -
+---
+
+[%sep:repeat(3)]
+<!-- Outputs: --- -->
+```
+
+## Formatting Transforms
+
+### `format(FORMAT_STRING)`
+Formats a numeric value using `sprintf`-style formatting.
+
+```markdown
+---
+price: 42.5
+---
+
+[%price:format($%.2f)]
+<!-- Outputs: $42.50 -->
+```
+
+### `length`
+Returns the length of the value as a string.
+
+```markdown
+---
+text: Hello
+---
+
+[%text:length]
+<!-- Outputs: 5 -->
+```
+
+### `pad(WIDTH,CHAR)`
+Pads the value to the specified width with the specified character (default: space).
+
+```markdown
+---
+number: 42
+---
+
+[%number:pad(5,0)]
+<!-- Outputs: 00042 -->
+```
+
+### `contains(STRING)`
+Returns `"true"` if the value contains the specified string, `"false"` otherwise.
+
+```markdown
+---
+tags: javascript,html,css
+---
+
+[%tags:contains(javascript)]
+<!-- Outputs: true -->
+```
+
+## Date/Time Transforms
+
+### `strftime(FORMAT)`
+Formats a date using `strftime`-style format strings. Parses dates in formats like `YYYY-MM-DD`, `YYYY-MM-DD HH:MM`, or `YYYY-MM-DD HH:MM:SS`.
+
+```markdown
+---
+date: 2024-03-15
+---
+
+[%date:strftime(%Y)]
+<!-- Outputs: 2024 -->
+
+[%date:strftime(%B %d, %Y)]
+<!-- Outputs: March 15, 2024 -->
+```
+
+## Transform Chaining
+
+Multiple transforms can be chained together using colons. Each transform operates on the result of the previous transform:
+
+```markdown
+---
+title: hello world
+---
+
+[%title:title:split( ):first]
+<!--
+  1. title -> "Hello World"
+  2. split( ) -> ["Hello", "World"] (array)
+  3. first -> "Hello"
+-->
+```
+
+**Example with dates:**
+```markdown
+---
+date: 2024-03-15 14:30
+---
+
+[%date:strftime(%Y)]
+<!-- Outputs: 2024 -->
+```
+
+## Notes
+
+- Transforms are case-sensitive
+- Array transforms (`split`, `join`, `first`, `last`, `slice`) work together - use `split` to create an array, then apply other array transforms
+- The `slice` transform automatically converts non-array strings into character arrays if needed
+- Regex patterns in `replace` support POSIX Extended Regular Expressions and can include character classes like `[0-9]+`
+- Date parsing supports common formats but may not handle all date string formats
+- Unknown transforms are ignored and return the original value

data/ext/apex_ext/apex_src/documentation/app-transformed/Modes.md

@@ -0,0 +1,193 @@
+# Processor Modes
+
+Apex supports multiple processor modes, each optimized for compatibility with different Markdown flavors. You can select between unified, multimarkdown, commonmark, kramdown, and gfm from the **Settings->Processor** panel.
+
+## Overview
+
+| Mode         | Description                 | Default ID Format |
+| ------------ | --------------------------- | ----------------- |
+| `unified`    | All features enabled        | GFM               |
+| `gfm`        | GitHub Flavored Markdown    | GFM               |
+| `mmd`        | MultiMarkdown compatibility | MultiMarkdown     |
+| `kramdown`   | Kramdown compatibility      | Kramdown          |
+| `commonmark` | Pure CommonMark spec        | GFM               |
+
+## Unified Mode (Default)
+
+Unified mode enables all features from all other modes. This is the default mode.
+
+### Enabled Features
+
+- ✅ Tables (GFM style)
+- ✅ Strikethrough (`~~text~~`)
+- ✅ Task lists (`- [ ]` and `- [x]`)
+- ✅ Autolinks (URLs and emails)
+- ✅ Footnotes (reference and inline styles)
+- ✅ Definition lists
+- ✅ Smart typography
+- ✅ Math support (`$inline$` and `$$display$$`)
+- ✅ Wiki links (`[[Page]]`) - Enable in **Settings->Processor->Wiki Links** (disabled by default)
+- ✅ Critic Markup
+- ✅ Callouts
+- ✅ File includes
+- ✅ Metadata blocks (YAML, MMD, Pandoc)
+- ✅ Metadata variables (`[%key]`) - See [Metadata Transforms](Metadata-Transforms) for transform syntax
+- ✅ Abbreviations
+- ✅ Inline Attribute Lists (IAL)
+- ✅ Relaxed tables (default)
+- ✅ GitHub Emoji (`:emoji_name:`)
+
+### ID Format
+
+- Default: GFM format
+- Can be overridden in **Settings->Processor->Header ID Format**
+
+## GFM Mode
+
+GitHub Flavored Markdown compatibility mode. Select this in **Settings->Processor->Mode**.
+
+### Enabled Features
+
+- ✅ Tables
+- ✅ Strikethrough
+- ✅ Task lists
+- ✅ Autolinks
+- ✅ Hard line breaks (newlines become `<br>`)
+
+### Disabled Features
+
+- ❌ Footnotes
+- ❌ Definition lists
+- ❌ Smart typography
+- ❌ Math
+- ❌ Wiki links
+- ❌ Critic Markup
+- ❌ Callouts
+- ❌ File includes
+- ❌ Metadata
+- ❌ Abbreviations
+- ❌ IAL
+- ❌ Relaxed tables
+
+### ID Format
+
+- GFM format (cannot be changed)
+
+## MultiMarkdown Mode
+
+MultiMarkdown compatibility mode. Select this in **Settings->Processor->Mode**.
+
+### Enabled Features
+
+- ✅ Tables
+- ✅ Footnotes (reference style)
+- ✅ Definition lists
+- ✅ Smart typography
+- ✅ Math support
+- ✅ Metadata blocks (YAML, MMD, Pandoc)
+- ✅ Metadata variables (`[%key]`) - See [Metadata Transforms](Metadata-Transforms) for transform syntax
+- ✅ Abbreviations
+- ✅ File includes
+
+### Disabled Features
+
+- ❌ Strikethrough
+- ❌ Task lists
+- ❌ Wiki links
+- ❌ Critic Markup
+- ❌ Callouts
+- ❌ IAL
+- ❌ Relaxed tables
+
+### ID Format
+
+- MultiMarkdown format (cannot be changed)
+
+## Kramdown Mode
+
+Kramdown compatibility mode. Select this in **Settings->Processor->Mode**.
+
+### Enabled Features
+
+- ✅ Tables
+- ✅ Footnotes (reference and inline styles)
+- ✅ Definition lists
+- ✅ Smart typography
+- ✅ Math support
+- ✅ Inline Attribute Lists (IAL)
+- ✅ Abbreviations
+- ✅ Relaxed tables (default)
+
+### Disabled Features
+
+- ❌ Strikethrough
+- ❌ Task lists
+- ❌ Wiki links
+- ❌ Critic Markup
+- ❌ Callouts
+- ❌ File includes
+- ❌ Metadata
+- ❌ Autolinks
+
+### ID Format
+
+- Kramdown format (cannot be changed)
+
+## CommonMark Mode
+
+Pure CommonMark specification compliance. No extensions. Select this in **Settings->Processor->Mode**.
+
+### Enabled Features
+
+- ✅ Basic Markdown only (headers, lists, emphasis, links, code, blockquotes, etc.)
+
+### Disabled Features
+
+- ❌ All extensions (tables, footnotes, etc.)
+
+### ID Format
+
+- GFM format (for consistency)
+
+## Feature Comparison Table
+
+| Feature          | Unified | GFM | MMD | Kramdown | CommonMark |
+| ---------------- | ------- | --- | --- | -------- | ---------- |
+| Tables           | ✅       | ✅   | ✅   | ✅        | ❌          |
+| Strikethrough    | ✅       | ✅   | ❌   | ❌        | ❌          |
+| Task Lists       | ✅       | ✅   | ❌   | ❌        | ❌          |
+| Footnotes        | ✅       | ❌   | ✅   | ✅        | ❌          |
+| Definition Lists | ✅       | ❌   | ✅   | ✅        | ❌          |
+| Smart Typography | ✅       | ❌   | ✅   | ✅        | ❌          |
+| Math             | ✅       | ❌   | ✅   | ✅        | ❌          |
+| Wiki Links       | ✅*      | ❌   | ❌   | ❌        | ❌          |
+| Critic Markup    | ✅       | ❌   | ❌   | ❌        | ❌          |
+| Callouts         | ✅       | ❌   | ❌   | ❌        | ❌          |
+| File Includes    | ✅       | ❌   | ✅   | ❌        | ❌          |
+| Metadata         | ✅       | ❌   | ✅   | ❌        | ❌          |
+| Abbreviations    | ✅       | ❌   | ✅   | ✅        | ❌          |
+| IAL              | ✅       | ❌   | ❌   | ✅        | ❌          |
+| Relaxed Tables   | ✅       | ❌   | ❌   | ✅        | ❌          |
+
+\* Wiki links are available in unified mode but **disabled by default**. Enable them in **Settings->Processor->Wiki Links**.
+
+## Choosing a Mode
+
+- **Unified** - Use when you want all features or need compatibility with multiple Markdown flavors
+- **GFM** - Use for GitHub compatibility or when publishing to GitHub
+- **MMD** - Use for MultiMarkdown compatibility or when you need metadata
+- **Kramdown** - Use for Kramdown compatibility or when you need IAL attributes
+- **CommonMark** - Use for strict CommonMark compliance or minimal output
+
+## Overriding Mode Defaults
+
+In unified mode, you can enable or disable specific features using the various settings in **Settings->Processor**. For example:
+
+- Disable footnotes: Uncheck **Settings->Processor->Footnotes**
+- Disable math: Uncheck **Settings->Processor->Math Support**
+- Enable wiki links: Check **Settings->Processor->Wiki Links**
+
+## Related
+
+- [Header IDs](Header-IDs) - How ID formats differ by mode
+- [Syntax](Syntax) - Syntax available in each mode