apex-ruby 1.0.18 → 1.0.20

data/ext/apex_ext/apex_src/documentation/app-transformed/Multi-File-Documents.md

@@ -0,0 +1,201 @@
+## Multi-file documents with Apex
+
+Apex can assemble larger documents from many smaller Markdown files. There are two primary tools for this:
+
+- **Combine**: Apex's native Markdown combiner, with optional GitBook-style `SUMMARY.md` support.
+- **MMD Merge**: A MultiMarkdown-compatible mode that reads a plain-text index file to stitch documents together.
+
+Both modes output **raw Markdown**, which Apex then processes into full HTML.
+
+---
+
+## Using Combine
+
+### Basic usage with multiple files
+
+You can combine multiple Markdown files. Apex will:
+
+- Read each file in order
+- Expand any include syntax it supports (Marked, MultiMarkdown, iA Writer)
+- Separate each document with blank lines
+
+To combine files in Marked, select multiple files and enable **Settings->Processor->Combine Files**. The app will automatically process them in order.
+
+### Using a GitBook-style `SUMMARY.md`
+
+When one of the files is named `SUMMARY.md`, Apex treats it as a **GitBook index**. It scans the file for Markdown links and combines the referenced pages in order:
+
+Example `SUMMARY.md`:
+
+```markdown
+# My Book
+
+- [Introduction](intro.md)
+- [Getting Started](getting-started.md)
+- [Advanced Topics](advanced.md)
+  - [Performance](performance.md)
+  - [Appendix](appendix.md)
+```
+
+When you open `SUMMARY.md` in Marked with combine mode enabled, Apex will:
+
+- Follow the link targets (`intro.md`, `getting-started.md`, etc.)
+- Expand any file includes inside those documents
+- Process everything into a single document
+
+---
+
+## Using MMD Merge (MultiMarkdown-style)
+
+MMD Merge emulates the original MultiMarkdown `mmd_merge.pl` script. It reads one or more **plain text index files** and:
+
+- Skips blank lines
+- Treats lines whose first non-whitespace character is `#` as **comments**
+- Treats all other lines as filenames to include
+- Uses **indentation** (tabs or groups of four spaces) to increase the header level of the included file
+
+**Important:** MMD merge documents must start with a `#merge` line to be automatically detected by Marked.
+
+### Example mmd_merge index file
+
+```text
+#merge
+metadata.txt
+Chapter-1.md
+    sub-chapter-1-1.md
+    sub-chapter-1-2.md
+Chapter-2.md
+    sub-chapter-2-1.md
+    sub-chapter-2-2.md
+FAQ.md
+Acknowledgments.md
+```
+
+Behavior:
+
+- `metadata.txt`, `Chapter-1.md`, `Chapter-2.md`, `FAQ.md`, `Acknowledgments.md` are included at their original heading levels.
+- Files indented by **one tab or four spaces** (`sub-chapter-1-1.md`, `sub-chapter-1-2.md`, etc.) have all headings shifted **down one level**:
+  - `# Heading` → `## Heading`
+  - `## Subheading` → `### Subheading`, etc.
+
+Comments are supported:
+
+```text
+#merge
+# This is my book index
+metadata.txt
+
+# Part 1
+Chapter-1.md
+    sub-chapter-1-1.md
+```
+
+Lines starting with `#` after optional whitespace are ignored (except for the required `#merge` line at the start).
+
+When you open an MMD merge index file in Marked, the app will automatically detect the `#merge` line and process the file accordingly. You can also enable **Settings->Processor->MMD Merge** to force this mode.
+
+Notes:
+
+- MMD Merge does **not** itself expand includes; it just concatenates files and shifts headings.
+- For full MultiMarkdown semantics, set the processor mode to MultiMarkdown in **Settings->Processor->Mode**.
+
+---
+
+## Combining multiple files directly
+
+You don't need an index file to combine documents. With combine mode enabled, you can select multiple files and Marked will process them in order.
+
+This approach works well when:
+
+- The order is simple and fixed
+- You don't need header-level shifting based on indentation
+
+If you need finer control over header levels, use:
+
+- MMD Merge with an index file (indentation-based)
+- Or explicit headings inside your individual files
+
+---
+
+## Building multi-file documents with include syntax
+
+In addition to combine and MMD merge modes, Apex supports **file includes** inside Markdown. This lets you treat one file as the "root" and pull in other files at specific points.
+
+Supported include syntaxes:
+
+- **MultiMarkdown**: `{{file.md}}`
+- **Marked**: `<<[file.md]` (Markdown include), `<<(file.ext)` (code include), `<<{file.html}` (raw HTML)
+- **iA Writer**: `/file.md` at the start of a line
+
+### MultiMarkdown include example
+
+`book.md`:
+
+```markdown
+Title: My Included Book
+
+{{metadata.md}}
+
+{{intro.md}}
+{{chapter1.md}}
+{{chapter2.md}}
+{{appendix.md}}
+```
+
+When you open `book.md` in Marked, Apex will automatically expand all the includes.
+
+### Marked-style include example
+
+`book.md`:
+
+```markdown
+# My Marked-Style Book
+
+<<[intro.md]
+<<[chapter1.md]
+<<[chapter2.md]
+```
+
+Marked will process these includes automatically.
+
+### iA Writer-style include example
+
+`book.md`:
+
+```markdown
+# My iA Writer-Style Book
+
+/intro.md
+/chapter1.md
+/chapter2.md
+```
+
+Marked will process these includes automatically.
+
+### Combining includes with combine mode
+
+You can combine both approaches: use includes inside files and then use combine mode on top. This is especially useful when:
+
+- Each part has its own local includes
+- You want a single final HTML output
+
+---
+
+## Choosing between Combine, MMD Merge, and includes
+
+- **Use Combine** when:
+  - You want Apex to expand includes
+  - You like GitBook-style `SUMMARY.md` navigation
+  - You just want to pass multiple files and let Apex concatenate them
+
+- **Use MMD Merge** when:
+  - You have existing MultiMarkdown workflows or `mmd_merge.pl` index files
+  - You want indentation-based header level shifting
+  - You want a very simple, text-only index format
+  - Remember: files must start with `#merge` to be auto-detected
+
+- **Use include syntax** when:
+  - You want one "master" document that controls where content appears
+  - You prefer to keep structure inside Markdown files rather than an external index
+
+All three can be mixed and matched, and all ultimately produce **Markdown** that Apex processes into HTML, PDF (via Pandoc), or other formats in your toolchain.