Multiline Directives

XMD supports clean multiline syntax for complex operations, including advanced scripting features like array literals, for loops with bodies, and dynamic imports.

Basic Syntax

<!-- xmd:
directive1
directive2
directive3
-->

Advanced Script Blocks

XMD now supports script-like syntax with arrays, loops, and string concatenation:

<!-- xmd:
set items = ["file1.md", "file2.md", "file3.md"]
set content = ""
for item in items
    content += "### " + import item + "\n\n"
-->
<div class="home"><h1 class="page-heading">XMD Documentation</h1><h1 id="xmd-documentation">XMD Documentation</h1>

<p>Welcome to XMD - eXtended MarkDown processor with advanced scripting capabilities.</p>

<h2 id="getting-started">Getting Started</h2>

<ul>
  <li><a href="/xmd/quick-start.html">Quick Start Guide</a> - Get up and running in 5 minutes</li>
  <li><a href="/xmd/quick-start.html#installation">Installation</a> - Installation options</li>
  <li><a href="/xmd/quick-start.html#basic-usage">Basic Usage</a> - Your first XMD document</li>
  <li><a href="/xmd/quick-start.html#updating-xmd">Updating XMD</a> - Keep your installation current</li>
</ul>

<h2 id="user-guide">User Guide</h2>

<ul>
  <li><a href="/xmd/cli-reference.html">CLI Reference</a> - Command-line options and examples</li>
  <li><a href="/xmd/upgrade-guide.html">Upgrade Guide</a> - Keep your installation current</li>
  <li><a href="/xmd/multiline-directives.html">Multiline Directives</a> - Advanced scripting features</li>
  <li><a href="/xmd/cli-reference.html#watch-mode-for-development">Watch Mode</a> - Real-time file processing</li>
  <li><a href="../examples/">Examples</a> - Real-world use cases</li>
</ul>

<h2 id="language-reference">Language Reference</h2>

<h3 id="variables">Variables</h3>
<ul>
  <li>Set variables with <code class="language-plaintext highlighter-rouge">set</code></li>
  <li>Use variables with ``</li>
  <li>Support for strings, numbers, booleans, arrays, objects</li>
  <li>Array literals: <code class="language-plaintext highlighter-rouge">["item1", "item2", "item3"]</code></li>
  <li>Variable initialization: <code class="language-plaintext highlighter-rouge">set varname</code> (without assignment)</li>
</ul>

<h3 id="advanced-scripting">Advanced Scripting</h3>
<ul>
  <li><strong>Array Processing</strong>: Iterate over arrays with <code class="language-plaintext highlighter-rouge">for item in array</code></li>
  <li><strong>String Concatenation</strong>: Use <code class="language-plaintext highlighter-rouge">+</code> operator for string combination</li>
  <li><strong>Compound Assignment</strong>: Use <code class="language-plaintext highlighter-rouge">+=</code> for accumulating content</li>
  <li><strong>Dynamic Imports</strong>: <code class="language-plaintext highlighter-rouge">import variable_name</code> where variable contains filename</li>
  <li><strong>Expression Evaluation</strong>: Complex expressions like <code class="language-plaintext highlighter-rouge">"prefix " + import file + " suffix"</code></li>
</ul>

<h3 id="commands">Commands</h3>
<ul>
  <li>Execute with <code class="language-plaintext highlighter-rouge">exec</code></li>
  <li>Capture output with <code class="language-plaintext highlighter-rouge">set var = exec command</code></li>
  <li>Dynamic buffer allocation for large command outputs</li>
  <li>Security controls with <code class="language-plaintext highlighter-rouge">--no-exec</code></li>
</ul>

<h3 id="functions">Functions</h3>
<ul>
  <li><code class="language-plaintext highlighter-rouge">print(variable)</code> - Output variable value</li>
  <li><code class="language-plaintext highlighter-rouge">cmd("command")</code> - Execute and return output</li>
</ul>

<h3 id="control-flow">Control Flow</h3>
<ul>
  <li><code class="language-plaintext highlighter-rouge">if/elif/else/endif</code> - Conditional execution</li>
  <li><code class="language-plaintext highlighter-rouge">for/endfor</code> - Loop over arrays and ranges</li>
  <li>Advanced for loops with bodies and indentation</li>
  <li>Logical operators: <code class="language-plaintext highlighter-rouge">&amp;&amp;</code>, <code class="language-plaintext highlighter-rouge">||</code>, <code class="language-plaintext highlighter-rouge">!</code></li>
</ul>

<h3 id="script-blocks">Script Blocks</h3>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>&lt;!-- xmd:
set files = ["config.md", "setup.md", "deploy.md"]
set documentation = ""
for file in files
    documentation += "## " + import file + "<span class="se">\n\n</span>"
--&gt;

</code></pre></div></div>

<h2 id="developer-guide">Developer Guide</h2>

<ul>
  <li><a href="dev/">Developer Documentation</a> - Architecture and contribution guide</li>
  <li><a href="dev/api/">API Reference</a> - Function documentation</li>
  <li><a href="dev/testing.md">Testing Guide</a> - How to run and write tests</li>
</ul>

<h2 id="support">Support</h2>

<ul>
  <li><a href="https://github.com/akaoio/xmd/issues">GitHub Issues</a> - Bug reports</li>
  <li><a href="https://github.com/akaoio/xmd/discussions">Discussions</a> - Q&amp;A and ideas</li>
</ul>
</div>

Examples

Variable Declaration

<!-- xmd:
set name = "Project X"
set version = "2.0.0"
set author = "Development Team"
set date = exec date +"%Y-%m-%d"
-->

Command Execution

<!-- xmd:
set hostname = exec hostname
set kernel = exec uname -r
set uptime = exec uptime -p
-->

System:  ()
Uptime:

Functions

<!-- xmd:
set user = exec whoami
set home = exec echo $HOME
print(user)
print(home)
-->

Control Flow

<!-- xmd:
set env = "production"
set debug = false
-->

<!-- xmd: if env == "production" -->
⚠️ Production Environment
<!-- xmd: endif -->

<!-- xmd: if debug -->
Debug output enabled
<!-- xmd: else -->
Debug output disabled
<!-- xmd: endif -->

Advanced Array Processing

<!-- xmd:
set services = ["nginx", "mysql", "redis", "postgresql"]
set report = "# Service Status Report\n\n"
for service in services
    set status = exec systemctl is-active service 2>/dev/null || echo "inactive"
    report += "- **" + service + "**: " + status + "\n"
-->

Dynamic Documentation Generation

<!-- xmd:
set chapters = ["introduction.md", "setup.md", "usage.md", "api.md"]
set documentation = "# Complete Guide\n\n"
for chapter in chapters
    documentation += import chapter + "\n\n---\n\n"
-->

Advanced Examples

Project Status Report

<!-- xmd:
set project = "MyApp"
set branch = exec git branch --show-current
set commits = exec git rev-list --count HEAD
set lastCommit = exec git log -1 --pretty=format:"%h - %s"
-->

#  Status

- Branch: 
- Total commits: 
- Last commit: 

<!-- xmd:
print("Generated at: ")
cmd("date '+%Y-%m-%d %H:%M:%S'")
-->

Dynamic Configuration

<!-- xmd:
set config = {
  "app": "WebServer",
  "port": 8080,
  "ssl": true,
  "workers": 4
}
-->

<!-- xmd: for key in ["app", "port", "ssl", "workers"] -->
: 
<!-- xmd: endfor -->

Best Practices

  1. Group Related Operations: Keep related directives together in multiline blocks
  2. Use Functions for Output: print() and cmd() work great in multiline blocks
  3. Combine with Loops: Multiline blocks inside loops for complex iterations
  4. Clear Variable Names: Use descriptive names for better readability

Supported Features

Core Directives

  • set - Variable assignment with array literals
  • exec - Command execution with dynamic buffer allocation
  • if/elif/else/endif - Conditionals
  • print() - Output function
  • cmd() - Command function
  • import - Module imports with variable support

Advanced Scripting Features

  • Array Literals: ["item1", "item2", "item3"]
  • For Loops with Bodies: Multi-line loop bodies with indentation
  • String Concatenation: Use + operator to combine strings
  • Dynamic Imports: import variable_name where variable contains filename
  • Variable Initialization: set varname without assignment
  • Compound Assignment: variable += "additional content"

Script Block Detection

XMD automatically detects advanced script syntax and uses the enhanced processor when:

  • Array literals are present: ["item1", "item2"]
  • For loops with bodies are used: for item in array
  • Compound assignment operators are used: +=

Expression Evaluation

  • String literals with escape sequences: "Hello\nWorld"
  • Variable references in expressions
  • Import calls within concatenation: "### " + import filename + "\n"
  • Complex expressions: result += prefix + import file + suffix