apex-ruby 1.0.17 → 1.0.20

data/ext/apex_ext/apex_src/documentation/app-transformed/Inline-Attribute-Lists.md

@@ -0,0 +1,516 @@
+# Inline Attribute Lists (IALs) and Attribute List Definitions (ALDs)
+
+Inline Attribute Lists (IALs) allow you to add HTML attributes (IDs, classes, and custom key-value pairs) to Markdown elements. Attribute List Definitions (ALDs) let you define reusable attribute sets that can be referenced multiple times.
+
+This feature is available in **Kramdown** and **unified** modes.
+
+## Overview
+
+IALs use the syntax `{: attributes}` (Kramdown-style) or `{#id .class}` (Pandoc-style) and can be applied to:
+- **Block-level elements**: Headings, paragraphs, lists, blockquotes, code blocks, tables
+- **Span-level elements**: Links, images, emphasis (italic), strong (bold), code spans
+
+Apex supports both formats:
+- **Kramdown-style**: `{: #id .class key="value"}` - requires a colon after the opening brace
+- **Pandoc-style**: `{#id .class key="value"}` - no colon required
+
+Both formats work identically. For example, `{#my-id .my-class}` is equivalent to `{:#my-id .my-class}`.
+
+ALDs define reusable attribute sets with the syntax `{:ref-name: attributes}` and can be referenced in IALs using `{:ref-name}`.
+
+## Block-Level IALs
+
+For block-level elements, IALs appear on a separate line immediately after the element (no blank line).
+
+### Paragraphs
+
+```markdown
+This is a paragraph with an ID and classes.
+{: #para-id .important .note}
+
+This is a paragraph using Pandoc-style IAL.
+{#para-id-2 .important .note}
+
+Another paragraph with custom attributes.
+{: title="Important Note" lang="en"}
+```
+
+Output:
+```html
+<p id="para-id" class="important note">This is a paragraph with an ID and classes.</p>
+<p id="para-id-2" class="important note">This is a paragraph using Pandoc-style IAL.</p>
+<p title="Important Note" lang="en">Another paragraph with custom attributes.</p>
+```
+
+### Headings
+
+Headings can have IALs on the same line or the next line:
+
+**Same line:**
+```markdown
+# Heading {: #custom-id}
+## Another Heading {: .highlight .large}
+## Pandoc-style Heading {#pandoc-id .highlight}
+```
+
+**Next line:**
+```markdown
+# Heading
+{: #custom-id .highlight}
+
+# Pandoc-style Heading
+{#pandoc-id-2 .highlight}
+
+## Another Heading
+{: .section-title lang="en"}
+```
+
+Output:
+```html
+<h1 id="custom-id">Heading</h1>
+<h2 class="highlight large">Another Heading</h2>
+<h2 id="pandoc-id" class="highlight">Pandoc-style Heading</h2>
+<h1 id="custom-id" class="highlight">Heading</h1>
+<h1 id="pandoc-id-2" class="highlight">Pandoc-style Heading</h1>
+<h2 class="section-title" lang="en">Another Heading</h2>
+```
+
+### Lists
+
+```markdown
+- Item 1
+- Item 2
+- Item 3
+{: .unordered-list .compact}
+
+1. First
+2. Second
+3. Third
+{: #ordered-list .numbered}
+```
+
+Output:
+```html
+<ul class="unordered-list compact">
+  <li>Item 1</li>
+  <li>Item 2</li>
+  <li>Item 3</li>
+</ul>
+<ol id="ordered-list" class="numbered">
+  <li>First</li>
+  <li>Second</li>
+  <li>Third</li>
+</ol>
+```
+
+### Blockquotes
+
+```markdown
+> This is a quote.
+{: .quote .inspirational}
+
+> Another quote with attribution.
+{: cite="https://example.com"}
+```
+
+Output:
+```html
+<blockquote class="quote inspirational">
+  <p>This is a quote.</p>
+</blockquote>
+<blockquote cite="https://example.com">
+  <p>Another quote with attribution.</p>
+</blockquote>
+```
+
+### Tables
+
+Tables can have IALs applied on a separate line after the table:
+
+```markdown
+| Key | Value |
+| --- | :---: |
+| one |   1   |
+| two |   2   |
+{: #data-table .striped .bordered}
+```
+
+Output:
+```html
+<table id="data-table" class="striped bordered">
+  <!-- table content -->
+</table>
+```
+
+**Pandoc table_attributes extension:**
+
+Apex also supports Pandoc's `table_attributes` extension, which allows IAL attributes to be specified in table captions. When using Pandoc-style captions with the `: Caption` syntax, IAL attributes in the caption are extracted and applied to the table:
+
+```markdown
+| Key | Value |
+| --- | :---: |
+| one |   1   |
+| two |   2   |
+
+: Key value table {#table-id .testing key="value"}
+```
+
+This is equivalent to:
+
+```markdown
+| Key | Value |
+| --- | :---: |
+| one |   1   |
+| two |   2   |
+{: #table-id .testing key="value"}
+```
+
+Both Kramdown-style IALs (`{: #id .class}`) and Pandoc-style IALs without the colon (`{#id .class}`) are supported in table captions.
+
+**Note:** The `: Caption` syntax only works when adjacent to a table to avoid conflicts with definition list syntax. See [Syntax](Syntax) for more details on table captions.
+
+## Inline IALs
+
+Inline IALs appear immediately after the element they apply to, within the same paragraph.
+
+### Links
+
+```markdown
+This is a [regular link](https://example.com) without attributes.
+
+Here's a [styled link](https://example.com){:.button} with a button class.
+
+Here's a [Pandoc-style link](https://example.com){#link-id .button} with attributes.
+
+You can have [multiple links](https://example.com){:.link-primary} with [different classes](https://example.com){:.link-secondary} in the same paragraph.
+
+A link with [custom attributes](https://example.com){:rel="nofollow" title="External Link"}.
+```
+
+Output:
+```html
+<p>This is a <a href="https://example.com">regular link</a> without attributes.</p>
+<p>Here's a <a href="https://example.com" class="button">styled link</a> with a button class.</p>
+<p>Here's a <a href="https://example.com" id="link-id" class="button">Pandoc-style link</a> with attributes.</p>
+<p>You can have <a href="https://example.com" class="link-primary">multiple links</a> with <a href="https://example.com" class="link-secondary">different classes</a> in the same paragraph.</p>
+<p>A link with <a href="https://example.com" rel="nofollow" title="External Link">custom attributes</a>.</p>
+```
+
+### Images
+
+```markdown
+![Regular image](image.png)
+
+![Styled image](logo.png){:.logo .centered}
+
+![Image with ID](icon.png){:#site-icon .icon}
+
+![Image with title](photo.jpg){:title="Photo Title" alt="Photo description"}
+```
+
+Output:
+```html
+<p><img src="image.png" alt="Regular image" /></p>
+<p><img src="logo.png" alt="Styled image" class="logo centered" /></p>
+<p><img src="icon.png" alt="Image with ID" id="site-icon" class="icon" /></p>
+<p><img src="photo.jpg" alt="Image with title" title="Photo Title" alt="Photo description" /></p>
+```
+
+### Emphasis and Strong
+
+```markdown
+This paragraph has **bold text**{:.bold-style} with a custom class and *italic text*{:.italic-style} with another class.
+
+You can combine **bold**{:.bold} and *italic*{:.italic} in the same paragraph with different styles.
+
+Nested **bold with *italic*{:.nested-italic} inside**{:.bold-wrapper} works too.
+```
+
+Output:
+```html
+<p>This paragraph has <strong class="bold-style">bold text</strong> with a custom class and <em class="italic-style">italic text</em> with another class.</p>
+<p>You can combine <strong class="bold">bold</strong> and <em class="italic">italic</em> in the same paragraph with different styles.</p>
+<p>Nested <strong class="bold-wrapper">bold with <em class="nested-italic">italic</em> inside</strong> works too.</p>
+```
+
+### Code Spans
+
+```markdown
+Use `inline code`{:.code-inline} for code snippets with styling.
+
+You can have multiple `code spans`{:.code-1} and `more code`{:.code-2} with different classes.
+```
+
+Output:
+```html
+<p>Use <code class="code-inline">inline code</code> for code snippets with styling.</p>
+<p>You can have multiple <code class="code-1">code spans</code> and <code class="code-2">more code</code> with different classes.</p>
+```
+
+## Attribute Syntax
+
+IALs support three types of attributes:
+
+### 1. IDs
+
+Use `#` followed by the ID name:
+
+```markdown
+# Heading {: #section-1}
+```
+
+Output: `<h1 id="section-1">Heading</h1>`
+
+### 2. Classes
+
+Use `.` followed by the class name. Multiple classes can be specified:
+
+```markdown
+Paragraph.
+{: .important .note .highlight}
+```
+
+Output: `<p class="important note highlight">Paragraph.</p>`
+
+**Note:** Multiple `.class` specifiers are equivalent to a single `class` attribute with space-separated values.
+
+### 3. Key-Value Pairs
+
+Use `key="value"` or `key='value'` for custom attributes. Values can be quoted (single or double quotes) or unquoted:
+
+```markdown
+Paragraph.
+{: title="Important Note" lang="en" data-id="123"}
+
+Link with attributes.
+[Click here](url){:rel="nofollow" target="_blank"}
+```
+
+Output:
+```html
+<p title="Important Note" lang="en" data-id="123">Paragraph.</p>
+<p>Link with attributes.
+<a href="url" rel="nofollow" target="_blank">Click here</a></p>
+```
+
+**Quoted values:** Use quotes when values contain spaces or special characters:
+```markdown
+{: title="This is a title with spaces" lang="en-US"}
+```
+
+**Unquoted values:** Simple values without spaces can be unquoted:
+```markdown
+{: lang=en data-visible=true}
+```
+
+**Escaping quotes:** Inside quoted values, escape quotes with backslash:
+```markdown
+{: title="He said \"Hello\""}
+```
+
+### Combining Attributes
+
+All three types can be combined in a single IAL:
+
+```markdown
+# Heading
+{: #section-1 .important .highlight title="Section Title" lang="en"}
+```
+
+Output: `<h1 id="section-1" class="important highlight" title="Section Title" lang="en">Heading</h1>`
+
+## Attribute List Definitions (ALDs)
+
+ALDs let you define reusable attribute sets that can be referenced multiple times. This is useful for maintaining consistent styling across a document.
+
+### Defining ALDs
+
+ALDs use the syntax `{:ref-name: attributes}` and can appear anywhere in your document (though typically at the end for organization):
+
+```markdown
+# Header 1
+{:header-style}
+
+# Header 2
+{:header-style}
+
+# Header 3
+{:header-style}
+
+{:header-style: #section-title .large .bold lang="en"}
+```
+
+Output:
+```html
+<h1 id="section-title" class="large bold" lang="en">Header 1</h1>
+<h1 id="section-title" class="large bold" lang="en">Header 2</h1>
+<h1 id="section-title" class="large bold" lang="en">Header 3</h1>
+```
+
+### ALD Syntax
+
+ALD definitions follow the same attribute syntax as IALs:
+
+```markdown
+{:my-style: #my-id .class1 .class2 title="My Title" lang="en"}
+```
+
+### Referencing ALDs
+
+Reference an ALD in an IAL using just the reference name:
+
+```markdown
+# Heading
+{:my-style}
+
+Paragraph.
+{:my-style}
+```
+
+If the ALD `{:my-style: ...}` is defined, both elements will receive those attributes.
+
+### Mixed Usage
+
+You can mix ALD references with additional attributes in the same IAL. The additional attributes override or extend the ALD:
+
+```markdown
+{:base-style: #main .class1 .class2}
+
+# Heading 1
+{:base-style}
+
+# Heading 2
+{:base-style .class3}
+
+# Heading 3
+{:base-style #override-id}
+
+# Heading 4
+{:base-style .class3 rel="nofollow"}
+```
+
+Output:
+```html
+<h1 id="main" class="class1 class2">Heading 1</h1>
+<h1 id="main" class="class1 class2 class3">Heading 2</h1>
+<h1 id="override-id" class="class1 class2">Heading 3</h1>
+<h1 id="main" class="class1 class2 class3" rel="nofollow">Heading 4</h1>
+```
+
+**Behavior:**
+- **Classes**: Additional classes are appended to the ALD classes
+- **IDs**: If an ID is specified in the IAL, it overrides the ALD's ID
+- **Key-value attributes**: If a key exists in both ALD and IAL, the IAL value overrides the ALD value
+
+## Important Notes
+
+### Block-Level IAL Positioning
+
+For block-level elements, the IAL **must** appear immediately after the element with **no blank line** between them:
+
+**Correct:**
+```markdown
+Paragraph text.
+{: .class}
+```
+
+**Incorrect:**
+```markdown
+Paragraph text.
+
+{: .class}
+```
+
+The blank line will cause the IAL to be treated as a separate paragraph.
+
+### Inline IAL Positioning
+
+For inline elements, the IAL must appear immediately after the element, with optional whitespace:
+
+```markdown
+[link](url){:.class} text after
+**bold**{:.bold-style} more text
+```
+
+### Multiple Elements with Same Attributes
+
+When multiple links share the same URL, IALs are correctly matched using element indexing:
+
+```markdown
+Here's a [regular link](https://example.com) and [another link](https://example.com){:.button}.
+```
+
+Both links point to the same URL, but only the second one receives the `button` class.
+
+### Nested Elements
+
+IALs work with nested inline elements:
+
+```markdown
+**Bold text with *italic*{:.nested} inside**{:.wrapper}
+```
+
+The italic element gets the `nested` class, and the bold element gets the `wrapper` class.
+
+## Examples
+
+### Complete Example
+
+```markdown
+# Main Title
+{: #main-title .page-title}
+
+## Section 1
+{:section-heading}
+
+This paragraph has [a link](https://example.com){:.external-link} with styling.
+
+Another paragraph with **bold text**{:.highlight}.
+
+## Section 2
+{:section-heading}
+
+More content here.
+
+{:section-heading: .section .important lang="en"}
+```
+
+Output:
+```html
+<h1 id="main-title" class="page-title">Main Title</h1>
+<h2 class="section important" lang="en">Section 1</h2>
+<p>This paragraph has <a href="https://example.com" class="external-link">a link</a> with styling.</p>
+<p>Another paragraph with <strong class="highlight">bold text</strong>.</p>
+<h2 class="section important" lang="en">Section 2</h2>
+<p>More content here.</p>
+```
+
+### Using ALDs for Consistent Styling
+
+```markdown
+# Introduction
+{:intro}
+
+## Overview
+{:intro}
+
+## Details
+{:intro}
+
+{:intro: .chapter .first lang="en"}
+
+# Conclusion
+{:conclusion}
+
+## Summary
+{:conclusion}
+
+{:conclusion: .chapter .last lang="en"}
+```
+
+This allows you to maintain consistent styling across multiple elements by defining the attributes once and referencing them multiple times.
+
+## Related
+
+- [Syntax](Syntax) - Complete syntax reference
+- [Modes](Modes) - Understanding processor modes (IALs available in Kramdown and unified modes)