apex-ruby 1.0.17 → 1.0.20

data/ext/apex_ext/apex_src/objc/NSString+ApexPlugins.m

@@ -0,0 +1,169 @@
+/**
+ * NSString+ApexPlugins.m
+ */
+
+#import "NSString+ApexPlugins.h"
+#import <apex/plugins.h>
+
+NSErrorDomain const ApexPluginErrorDomain = @"ApexPluginErrorDomain";
+
+@interface ApexPluginInfo ()
+@property (nonatomic, copy, readwrite) NSString *pluginId;
+@property (nonatomic, copy, readwrite, nullable) NSString *title;
+@property (nonatomic, copy, readwrite, nullable) NSString *pluginDescription;
+@property (nonatomic, copy, readwrite, nullable) NSString *author;
+@property (nonatomic, copy, readwrite, nullable) NSString *homepage;
+@property (nonatomic, copy, readwrite, nullable) NSString *repo;
+@end
+
+@implementation ApexPluginInfo
+
++ (instancetype)infoWithCStruct:(const apex_plugin_info *)info {
+    if (!info || !info->id) return nil;
+    ApexPluginInfo *obj = [[self alloc] initPrivate];
+    obj.pluginId = [NSString stringWithUTF8String:info->id];
+    if (info->title) obj.title = [NSString stringWithUTF8String:info->title];
+    if (info->description) obj.pluginDescription = [NSString stringWithUTF8String:info->description];
+    if (info->author) obj.author = [NSString stringWithUTF8String:info->author];
+    if (info->homepage) obj.homepage = [NSString stringWithUTF8String:info->homepage];
+    if (info->repo) obj.repo = [NSString stringWithUTF8String:info->repo];
+    return obj;
+}
+
+- (instancetype)initPrivate {
+    return [super init];
+}
+
+@end
+
+static NSArray<ApexPluginInfo *> *ApexPluginInfosFromCatalog(apex_plugin_catalog *catalog) {
+    if (!catalog) return @[];
+
+    NSMutableArray<ApexPluginInfo *> *items = [NSMutableArray arrayWithCapacity:catalog->count];
+    for (size_t i = 0; i < catalog->count; i++) {
+        ApexPluginInfo *info = [ApexPluginInfo infoWithCStruct:&catalog->items[i]];
+        if (info) [items addObject:info];
+    }
+    return [items copy];
+}
+
+static NSError *ApexPluginMakeError(ApexPluginError code, const char *message) {
+    NSString *desc = message ? [NSString stringWithUTF8String:message] : @"Unknown plugin error";
+    return [NSError errorWithDomain:ApexPluginErrorDomain
+                               code:code
+                           userInfo:@{NSLocalizedDescriptionKey: desc}];
+}
+
+@implementation ApexPluginCatalog
+
++ (NSString *)defaultDirectoryURL {
+    return [NSString stringWithUTF8String:APEX_PLUGIN_DIRECTORY_URL];
+}
+
++ (nullable NSArray<ApexPluginInfo *> *)fetchAvailablePlugins:(NSError **)error {
+    return [self fetchAvailablePluginsFromURL:self.defaultDirectoryURL error:error];
+}
+
++ (nullable NSArray<ApexPluginInfo *> *)fetchAvailablePluginsFromURL:(NSString *)url
+                                                               error:(NSError **)error {
+    if (!url.length) {
+        if (error) {
+            *error = ApexPluginMakeError(ApexPluginErrorFetchFailed, "URL is required");
+        }
+        return nil;
+    }
+
+    apex_plugin_catalog *catalog = apex_plugin_catalog_fetch_url(url.UTF8String);
+    if (!catalog) {
+        if (error) {
+            *error = ApexPluginMakeError(ApexPluginErrorFetchFailed,
+                                         "failed to fetch plugin directory");
+        }
+        return nil;
+    }
+
+    NSArray<ApexPluginInfo *> *items = ApexPluginInfosFromCatalog(catalog);
+    apex_plugin_catalog_free(catalog);
+    return items;
+}
+
++ (NSArray<ApexPluginInfo *> *)installedPluginsWithBaseDirectory:(NSString *)baseDirectory {
+    apex_plugin_discovery_options opts;
+    memset(&opts, 0, sizeof(opts));
+    opts.include_project = true;
+    opts.include_user_global = true;
+    if (baseDirectory.length > 0) {
+        opts.base_directory = baseDirectory.UTF8String;
+    }
+
+    apex_plugin_catalog *catalog = apex_plugins_list_installed(&opts);
+    if (!catalog) return @[];
+
+    NSArray<ApexPluginInfo *> *items = ApexPluginInfosFromCatalog(catalog);
+    apex_plugin_catalog_free(catalog);
+    return items;
+}
+
++ (BOOL)installPluginWithId:(NSString *)pluginId error:(NSError **)error {
+    return [self installPluginFromRepository:pluginId allowUntrustedSource:NO error:error];
+}
+
++ (BOOL)installPluginFromRepository:(NSString *)idOrRepo
+              allowUntrustedSource:(BOOL)allowUntrusted
+                             error:(NSError **)error {
+    if (!idOrRepo.length) {
+        if (error) {
+            *error = ApexPluginMakeError(ApexPluginErrorInstallFailed, "plugin id is required");
+        }
+        return NO;
+    }
+
+    char errbuf[512];
+    errbuf[0] = '\0';
+
+    apex_plugin_install_options opts;
+    memset(&opts, 0, sizeof(opts));
+    opts.allow_untrusted_repo = allowUntrusted;
+    opts.run_post_install = true;
+
+    int rc = apex_plugin_install(idOrRepo.UTF8String, &opts, errbuf, sizeof(errbuf));
+    if (rc != 0) {
+        if (error) {
+            *error = ApexPluginMakeError(ApexPluginErrorInstallFailed,
+                                         errbuf[0] ? errbuf : "install failed");
+        }
+        return NO;
+    }
+    return YES;
+}
+
++ (BOOL)uninstallPluginWithId:(NSString *)pluginId error:(NSError **)error {
+    if (!pluginId.length) {
+        if (error) {
+            *error = ApexPluginMakeError(ApexPluginErrorUninstallFailed, "plugin id is required");
+        }
+        return NO;
+    }
+
+    char errbuf[512];
+    errbuf[0] = '\0';
+    int rc = apex_plugin_uninstall(pluginId.UTF8String, errbuf, sizeof(errbuf));
+    if (rc != 0) {
+        if (error) {
+            *error = ApexPluginMakeError(ApexPluginErrorUninstallFailed,
+                                         errbuf[0] ? errbuf : "uninstall failed");
+        }
+        return NO;
+    }
+    return YES;
+}
+
++ (nullable NSString *)globalPluginsDirectory {
+    char buf[1024];
+    if (apex_plugin_global_directory(buf, sizeof(buf)) != 0) {
+        return nil;
+    }
+    return [NSString stringWithUTF8String:buf];
+}
+
+@end

data/ext/apex_ext/apex_src/output.html

@@ -0,0 +1,87 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="generator" content="Apex 0.1.38">
+  <title>Timbuktu</title>
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
+      line-height: 1.6;
+      max-width: 800px;
+      margin: 2rem auto;
+      padding: 0 1rem;
+      color: #333;
+    }
+    pre { background: #f5f5f5; padding: 1rem; overflow-x: auto; }
+    code { background: #f0f0f0; padding: 0.2em 0.4em; border-radius: 3px; }
+    blockquote { border-left: 4px solid #ddd; margin: 0; padding-left: 1rem; color: #666; }
+    table { border-collapse: collapse; width: 100%%; }
+    th, td { border: 1px solid #ddd; padding: 0.5rem; }
+    th { background: #f5f5f5; }
+    .page-break { page-break-after: always; }
+    .callout { padding: 1rem; margin: 1rem 0; border-left: 4px solid; }
+    .callout-note { border-color: #3b82f6; background: #eff6ff; }
+    .callout-warning { border-color: #f59e0b; background: #fffbeb; }
+    .callout-tip { border-color: #10b981; background: #f0fdf4; }
+    .callout-danger { border-color: #ef4444; background: #fef2f2; }
+    ins { background: #d4fcbc; text-decoration: none; }
+    del { background: #fbb6c2; text-decoration: line-through; }
+    mark { background: #fff3cd; }
+    .critic.comment { background: #e7e7e7; color: #666; font-style: italic; }
+  </style>
+</head>
+<body>
+
+<h1 id="basic-heading">Basic Heading</h1>
+<h2 id="heading-with-spaces">Heading with Spaces</h2>
+<h3 id="multiple-spaces-here">Multiple   Spaces   Here</h3>
+<h4 id="heading-with-dash">Heading-with-dash</h4>
+<h5 id="headingwithunderscore">Heading_with_underscore</h5>
+<h6 id="headingwithdots">Heading.with.dots</h6>
+<h1 id="leading-space-test">Leading Space Test</h1>
+<h2 id="trailing-space-test">Trailing Space Test</h2>
+<h3 id="mixed-case-heading">Mixed Case Heading</h3>
+<h4 id="all-caps-heading">ALL CAPS HEADING</h4>
+<h1 id="punctuation-test-here">Punctuation Test, Here!</h1>
+<h2 id="more-punctuation-colons-semicolons">More Punctuation: Colons; Semicolons?</h2>
+<h3 id="special-characters">Special Characters @#$%^&amp;*</h3>
+<h4id="test">Parentheses (and brackets)</h4>
+<h5 id="test">Quotes “double” and ‘single’</h5>
+<h6 id="quotes-adoublea-and-asinglea">Backticks <code>code</code> in heading</h6>
+<h1 id="backticks-code-in-heading">Em Dash — Test</h1>
+<h2 id="em-dash-test">En Dash – Test</h2>
+<h3 id="en-dash-test">Mixed Dashes — and – here</h3>
+<h1 id="mixed-dashes-and-here">Diacritics Émoji Support</h1>
+<h2 id="diacritics-amoji-support">More Diacritics: Café, naïve, résumé</h2>
+<h3 id="more-diacritics-cafa-naave-rasuma">Accented Characters: àáâãäå</h3>
+<h4 id="accented-characters-aaaaaa">Cyrillic: Привет</h4>
+<h5 id="cyrillic-nn">Chinese: 你好</h5>
+<h6 id="chinese-aa">Japanese: こんにちは</h6>
+<h1 id="japanese-aaaaa">Numbers 123 in Heading</h1>
+<h2 id="numbers-123-in-heading">Math Symbols: 2+2=4</h2>
+<h3 id="math-symbols-224">Currency: $100, €50, £25</h3>
+<h1 id="currency-100-a50-a25">Leading Dash -Test</h1>
+<h2 id="leading-dash-test">Trailing Dash Test-</h2>
+<h3 id="trailing-dash-test">Multiple Dashes – Here</h3>
+<h4 id="multiple-dashes-here">Triple Dash — Test</h4>
+<h1 id="triple-dash-test">Empty After Processing</h1>
+<h2 id="empty-after-processing">[!@#<span class="math inline">\(%^&*()](mailto:!@#\)</span>%%5E&amp;*())</h2>
+<h3 id="5e">Only Special Characters</h3>
+<h1 id="only-special-characters">Very Long Heading That Should Still Generate a Valid ID Even When It Contains Many Words and Characters</h1>
+<h2 id="very-long-heading-that-should-still-generate-a-valid-id-even-when-it-contains-many-words-and-characters">Heading with URL: <a href="https://example.com/path">https://example.com/path</a></h2>
+<h3 id="heading-with-url">Email in heading: <a href="mailto:user@example.com">user@example.com</a></h3>
+<h1 id="email-in-heading">Heading with Markdown <em>bold</em> and <em>italic</em></h1>
+<h2 id="heading-with-markdown-and">Heading with <code>code</code> span</h2>
+<h3 id="heading-with-code-span">Heading with <a href="url">link</a></h3>
+<h4 id="heading-with">Heading with <img src="img.png" alt="image" /></h4>
+<h1 id="heading-with">Heading with HTML <tag></h1>
+<h2 id="heading-with-html">Mixed: Heading—with—dashes and spaces</h2>
+<h3id="2024">Complex: Hello, World! (Test)</h3>
+<h4 id="mixed-headingwithdashes-and-spaces">Edge Case:   Multiple   Spaces   Everywhere</h4>
+<h5 id="2024">Another: Test—Multiple—Dashes</h5>
+<h6 id="edge-case-multiple-spaces-everywhere">Final: [Special@#<span class="math inline">\(%Chars](mailto:Special@#\)</span>%Chars)</h6>
+
+</body>
+</html>

data/ext/apex_ext/apex_src/plans/quarto-mode.md

@@ -0,0 +1,442 @@
+# Plan: `--mode quarto` for Apex
+
+## Goal
+
+Add a **Quarto/Pandoc markdown compatibility mode** optimized for HTML rendering — not a Quarto runtime. Users should be able to point Apex at `.qmd`-style documents and get sensible HTML without running the full Quarto toolchain.
+
+**In scope:** Pandoc markdown syntax from [Quarto Markdown Basics](https://quarto.org/docs/authoring/markdown-basics.html)  
+**Out of scope:** cell execution, cross-refs (`@fig-…`), CSL/bibliography pipeline, multi-format output (PDF/Typst/Word), project/site rendering, conditional content, computed shortcodes
+
+---
+
+## Design principle
+
+**Quarto mode = unified + Pandoc preprocessors + Quarto defaults**
+
+Rather than a from-scratch mode, inherit `APEX_MODE_UNIFIED` and layer Quarto-specific preprocessing behind a master flag. That keeps maintenance manageable and avoids duplicating unified’s feature matrix.
+
+```c
+typedef enum {
+    /* ... existing ... */
+    APEX_MODE_UNIFIED = 4,
+    APEX_MODE_QUARTO  = 5   /* Pandoc/Quarto markdown for HTML */
+} apex_mode_t;
+```
+
+Add a convenience flag:
+
+```c
+bool enable_quarto_extensions;  /* Master switch for Pandoc/Quarto preprocessors */
+```
+
+Quarto mode sets this `true`; individual preprocessors can still be toggled via metadata/CLI for testing.
+
+---
+
+## Mode preset: `apex_options_for_mode(APEX_MODE_QUARTO)`
+
+Start from unified, then override:
+
+
+| Option                         | Quarto value | Rationale                      |
+| ------------------------------ | ------------ | ------------------------------ |
+| `enable_quarto_extensions`     | `true`       | Enables new preprocessors      |
+| `enable_quarto_callouts`       | `true`       | Core Quarto authoring          |
+| `enable_divs` / `enable_spans` | `true`       | Pandoc div/span syntax         |
+| `enable_alpha_lists`           | `true`       | `a.` / `A.` in Quarto examples |
+| `allow_mixed_list_markers`     | `true`       | Nested list markers            |
+| `enable_definition_lists`      | `true`       | Pandoc definition lists        |
+| `enable_footnotes`             | `true`       | Reference + inline `^[...]`    |
+| `enable_math`                  | `true`       | `$...$` / `$$...$$`            |
+| `enable_smart_typography`      | `true`       | `--`, `---`                    |
+| `enable_task_lists`            | `true`       | GFM task lists in Quarto       |
+| `enable_image_captions`        | `true`       | Figure captions                |
+| `unsafe`                       | `true`       | Raw HTML passthrough           |
+| `hardbreaks`                   | `false`      | Pandoc soft breaks, not GFM    |
+| `enable_wiki_links`            | `false`      | Not Quarto                     |
+| `enable_marked_extensions`     | `false`      | Marked-specific syntax off     |
+| `enable_py_callouts`           | `false`      | Quarto uses `:::`, not `!!!`   |
+| `enable_indices`               | `false`      | Not Pandoc/Quarto              |
+| `id_format`                    | GFM          | Quarto default header IDs      |
+
+
+**Refactor needed:** Many code paths gate on `mode == APEX_MODE_UNIFIED` (fenced divs, spans, autolink, etc.). Introduce helpers:
+
+```c
+static inline bool apex_mode_is_unified_family(apex_mode_t m) {
+    return m == APEX_MODE_UNIFIED || m == APEX_MODE_QUARTO;
+}
+```
+
+Replace hard-coded unified checks for divs, spans, fenced-div preprocessing, and similar features.
+
+---
+
+## Preprocessing pipeline
+
+New steps run **only when `enable_quarto_extensions`** is true. Proposed order (relative to existing pipeline in `apex.c`):
+
+```
+… existing preprocessors (metadata, includes, tables, def lists) …
+
+1. apex_preprocess_raw_content()      # {=format} blocks + inline
+2. apex_preprocess_code_fence_attrs() # ```{.python filename="..."}
+3. apex_preprocess_example_lists()  # (@) example list markers
+4. apex_preprocess_line_blocks()    # | line blocks
+5. apex_preprocess_roman_lists()    # i) ii) iii)
+6. apex_preprocess_quarto_shortcodes()  # {{< ... >}} (optional/plugin)
+7. apex_preprocess_quarto_callouts()    # existing
+8. apex_process_fenced_divs()           # existing (extend mode check)
+… parse …
+9. apex_postprocess_fig_alt()       # fig-alt → alt attribute
+10. apex_postprocess_diagrams()     # mermaid/graphviz wrappers
+11. apex_postprocess_semantic_spans() # .smallcaps, .underline, .mark CSS
+```
+
+Raw content and code-fence attribute normalization must run **before** cmark sees fenced code blocks.
+
+---
+
+## Phase 0 — Infrastructure (1–2 days)
+
+**Deliverables**
+
+- [ ] Add `APEX_MODE_QUARTO` to `apex.h`, Ruby bindings, docs
+- [ ] `apex_options_for_mode(APEX_MODE_QUARTO)` preset
+- [ ] CLI: `--mode quarto`; metadata `mode: quarto`
+- [ ] `apex_mode_is_unified_family()` and update mode gates in `apex.c`, `ial.c`
+- [ ] `tests/fixtures/quarto/` + smoke test: `apex --mode quarto fixtures/quarto/smoke.md`
+- [ ] Wiki page: `Quarto-Mode.md`; update `Modes.md`
+
+**Acceptance:** `apex --mode quarto doc.md` runs with quarto callouts enabled and divs/spans working.
+
+---
+
+## Phase 1 — Prerequisite fixes + low-hanging fruit (1–2 days)
+
+### 1a. Fix class-only bracketed spans
+
+Current bug: `[text]{.smallcaps}` → `<spanclass="smallcaps">`.
+
+**Fix:** In `attributes_to_html()`, ensure a leading space before `class=` when it’s the first attribute and no `id` precedes it (likely in the `first_attr` branch for classes).
+
+### 1b. `fig-alt` mapping
+
+Quarto: `![Caption](img.png){fig-alt="Alt text"}`
+
+**HTML output:**
+
+```html
+<figure>
+  <img src="img.png" alt="Alt text" />
+  <figcaption>Caption</figcaption>
+</figure>
+```
+
+Implement in image caption post-processing (`html_renderer.c` or IAL image attrs).
+
+### 1c. Semantic span classes
+
+Map Pandoc classes to CSS (inline or class-only):
+
+
+| Class        | HTML/CSS                                 |
+| ------------ | ---------------------------------------- |
+| `.smallcaps` | `font-variant: small-caps`               |
+| `.underline` | `text-decoration: underline`             |
+| `.mark`      | `background-color: yellow` (or `<mark>`) |
+
+
+Could be a small post-render pass or bundled CSS in `--standalone` when quarto mode is active.
+
+**Acceptance:** Quarto “Other Spans” examples render correctly.
+
+---
+
+## Phase 2 — Raw content `{=format}` (2–3 days)
+
+**Syntax**
+
+Block:
+
+```markdown
+```{=html}
+<iframe src="..."></iframe>
+```
+```
+
+Inline:
+
+```markdown
+`<a>html</a>`{=html}
+```
+
+**Behavior (HTML output)**
+
+
+| Format                  | Action                                                            |
+| ----------------------- | ----------------------------------------------------------------- |
+| `html`                  | Passthrough raw (requires `unsafe: true`)                         |
+| `latex`, `typst`, `tex` | Omit or wrap in `<!-- raw format=typst -->…<!-- /raw -->` comment |
+| unknown                 | Same as non-html: preserve as HTML comment for debugging          |
+
+
+**Implementation:** New `src/extensions/raw_content.c`
+
+- Scan fenced blocks; if info string matches `^=\w+$`, extract body and emit raw HTML block (or placeholder replaced post-parse)
+- Scan inline: backtick span immediately followed by `{=format}`
+
+**Tests:** `{=html}`, `{=latex}`, `{=typst}`, inline `{=html}`, ensure no processing inside `{=html}` blocks
+
+---
+
+## Phase 3 — List extensions (2–3 days)
+
+### 3a. Example lists `(@)`
+
+Pandoc `example_lists` extension — `(@)` is a **list marker**, not a standalone continuation line. See [Pandoc example lists](https://pandoc.org/MANUAL.html#extension-example_lists).
+
+```markdown
+(@)  My first example will be numbered (1).
+(@)  My second example will be numbered (2).
+
+Explanation of examples.
+
+(@)  My third example will be numbered (3).
+```
+
+Labeled markers `(@good)` are also supported; labels are stripped and items are numbered sequentially.
+
+**Implementation:** Preprocessor converts `(@)` / `(@label)` line-start markers to `1.`, `2.`, `3.`, … with document-wide sequential numbering. Interrupted lists rely on cmark's `start` attribute on continued `<ol>` blocks.
+
+**Not yet implemented:** repeating a prior example by reusing its label (`(@foo)` twice).
+
+### 3b. Roman numeral markers `i)`, `ii)`, `I)`, etc.
+
+Extend the alpha-list preprocessor (`apex.c` ~line 2649) with a third style:
+
+```html
+<ol style="list-style-type: lower-roman">
+```
+
+Detect `i)`, `ii)`, `iii)` (and uppercase) at list-item starts.
+
+### 3c. Line blocks
+
+```markdown
+| Line one
+|   preserved spaces
+| Line three
+```
+
+Pandoc line blocks: lines starting with `|` + space, continuation lines indented or also `|`.
+
+**Output:** `<div class="line-block">` with `<br />` or nested divs preserving spacing.
+
+**Tests:** Quarto’s nested list example (`1. / i) / A.`), line block example, `(@)` continuation
+
+---
+
+## Phase 4 — Code fence attributes (2 days)
+
+Quarto/Pandoc extended fences:
+
+```markdown
+```{.python filename="run.py" linenos=true}
+print("hello")
+```
+```
+
+**Preprocessor** normalizes to something cmark + Apex highlighting understand:
+
+```markdown
+```python
+print("hello")
+```
+```
+
+…plus metadata preserved for HTML output:
+
+```html
+<pre class="python" data-filename="run.py" data-linenos="true">
+```
+
+Or use existing code-line-numbers when `linenos` / `line-numbers` is present.
+
+**Parse rules:** Info string `{.class key="val" key2=val2}` — class becomes language if `.python`-style; remaining keys become data attributes on `<pre>`/`<code>`.
+
+---
+
+## Phase 5 — Diagrams (2–3 days)
+
+Quarto native diagram fences:
+
+```markdown
+```{mermaid}
+flowchart LR
+  A --> B
+```
+```
+
+**HTML strategy (pragmatic):**
+
+```html
+<pre class="mermaid">
+flowchart LR
+  A --> B
+</pre>
+```
+
+When `--standalone` + quarto mode, auto-suggest/include mermaid.js (you already have `--script mermaid`).
+
+Graphviz `{dot}` / `{graphviz}`: similar, or convert to `<img>` if a dot renderer is unavailable (document limitation).
+
+**Optional:** `enable_quarto_diagrams` flag; off = plain code block (current behavior).
+
+---
+
+## Phase 6 — Shortcodes (plugin-first, 2–4 days)
+
+Quarto shortcodes are a large surface area. Recommend **plugin, not core**:
+
+
+| Shortcode           | Apex approach                                       |
+| ------------------- | --------------------------------------------------- |
+| `{{< kbd >}}`       | Extend `apex-plugin-kbd` to accept Quarto syntax    |
+| `{{< pagebreak >}}` | Map to existing `{::pagebreak /}` or `<!--BREAK-->` |
+| `{{< video >}}`     | New small plugin → `<video>` / embed iframe         |
+| `{{< include >}}`   | Delegate to existing includes if possible           |
+
+
+**Core shim:** Optional lightweight preprocessor converts `{{< name args >}}` → plugin hook or known expansions; unknown shortcodes pass through with a warning in verbose mode.
+
+---
+
+## Phase 7 — Polish & compatibility toggles (ongoing)
+
+
+| Feature                       | Approach                                                                                     |
+| ----------------------------- | -------------------------------------------------------------------------------------------- |
+| `::: {.hidden}`               | Add `.hidden { display: none }` in quarto standalone CSS; math macros stay user’s problem    |
+| Empty div list reset `::: {}` | Verify list numbering; fix if cmark merges lists incorrectly                                 |
+| Strict blank-line-before-list | Optional `quarto_strict_lists` flag (off by default; Apex stays permissive unless requested) |
+| Cross-ref syntax `@fig-x`     | Pass through as text, or wrap in `<span class="quarto-xref">` for future filter              |
+| Citations `@key`              | Out of scope unless CSL integration is planned                                               |
+
+
+---
+
+## File layout
+
+```
+src/extensions/
+  raw_content.c / .h
+  quarto_lists.c / .h      # (@), roman lists, line blocks
+  code_fence_attrs.c / .h
+  quarto_diagrams.c / .h   # optional
+  quarto_shortcodes.c / .h # optional thin shim
+
+tests/
+  fixtures/quarto/
+    raw-content.md
+    lists.md
+    code-attrs.md
+    diagrams.md
+    callouts.md
+    spans.md
+  test_quarto_mode.c         # or section in test_extensions.c
+```
+
+---
+
+## CLI & metadata surface
+
+```bash
+apex doc.qmd --mode quarto
+apex doc.qmd --mode quarto --standalone --script mermaid
+```
+
+Metadata (in `.qmd` YAML):
+
+```yaml
+---
+title: My Doc
+mode: quarto
+quarto-callouts: true
+---
+```
+
+Individual toggles (for debugging / partial compatibility):
+
+```yaml
+quarto-raw: true
+quarto-list-continuation: true
+quarto-line-blocks: true
+quarto-roman-lists: true
+quarto-code-attrs: true
+quarto-diagrams: true
+quarto-shortcodes: false   # plugin handles it
+```
+
+---
+
+## Testing strategy
+
+1. **Fixture suite** — one `.md` per Quarto basics section; golden HTML snapshots
+2. **Regression** — existing unified tests must not break when quarto flags are off
+3. **Round-trip** — optional: quarto fixtures through `--to markdown` (future)
+4. **Live samples** — copy 2–3 snippets from quarto.org docs into fixtures
+
+Example acceptance test for Phase 2:
+
+```bash
+build/apex --mode quarto - <<'EOF'
+```{=html}
+<strong>raw</strong>
+```
+
+EOF
+
+# expect: **raw** not ```
+
+```
+
+```
+
+---
+
+## Suggested release milestones
+
+| Version | Phases | User-visible value |
+|---------|--------|-------------------|
+| **v1.2** | 0 + 1 | `--mode quarto` exists; callouts, spans, fig-alt work |
+| **v1.3** | 2 + 3 | Raw `{=typst}`/`{=html}`, `(@)`, roman lists, line blocks |
+| **v1.4** | 4 + 5 | Code fence attrs, mermaid fences |
+| **v1.5** | 6 + 7 | Shortcode plugins, polish |
+
+---
+
+## Risks & decisions
+
+1. **cmark limitations** — Line blocks and list continuation may need AST surgery, not just preprocessing. Budget time for post-parse fixes.
+2. **Raw `{=typst}` in HTML** — Document clearly: Apex preserves/emits comments; it does not compile Typst. Users targeting Typst still need Quarto/Pandoc.
+3. **Mode proliferation** — Keep quarto as unified-family; avoid a separate options matrix per feature.
+4. **Shortcodes vs plugins** — Core should not reimplement Quarto’s shortcode engine; plugins + thin shim is the right boundary.
+5. **Span bug** — Fix in unified too; not quarto-only.
+
+---
+
+## Recommended first PR (minimal viable quarto mode)
+
+Single PR touching:
+
+1. `APEX_MODE_QUARTO` + CLI + metadata
+2. `apex_mode_is_unified_family()` refactor
+3. Enable `--quarto-callouts` in quarto preset
+4. Fix bracketed span `class=` bug
+5. `fig-alt` mapping
+6. `tests/fixtures/quarto/smoke.md` + tests
+
+That gives a real `--mode quarto` users can try immediately, with raw content and list features as follow-up PRs.
+```
+