apex-ruby 1.0.29 → 1.0.31

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

@@ -1,201 +0,0 @@
-## 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.