RubyGems - apex-ruby - Versions diffs - 1.0.6 - Mend

apex-ruby 1.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (501) hide show

data/ext/apex_ext/apex_src/documentation/docsets/Apex.docset/Contents/Resources/Documents/Xcode-Integration.html ADDED Viewed

@@ -0,0 +1,2066 @@
+<!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.49">
+      <title>Document</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; }
+        tfoot td { background: #e8e8e8; }
+        figure.table-figure { width: fit-content; margin: 1em 0; }
+        figure.table-figure table { width: auto; }
+        figcaption { text-align: center; font-weight: bold; font-size: 0.8em; }
+        .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>
+  <style>
+/* Base styles */
+body {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  font-size: 17px;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+    "Helvetica Neue", Arial, sans-serif;
+  line-height: 1.65;
+  color: #1e293b;
+  background-color: #fff;
+}
+/* Sidebar / Main TOC - wider on larger screens */
+.main-toc,
+.sidebar {
+  position: fixed;
+  left: 0;
+  top: 0;
+  width: auto;
+  min-width: 180px;
+  max-width: 250px;
+  height: 100vh;
+  overflow-y: auto;
+  background: #1e293b;
+  color: rgba(255, 255, 255, 0.9);
+  border-right: 2px solid rgba(255, 255, 255, 0.1);
+  padding: 24px 20px 130px;
+  font-size: 14px;
+  z-index: 100;
+  margin-right: 1rem;
+  box-shadow: 4px 0 24px rgba(0, 0, 0, 0.08);
+  transition: transform 0.3s ease;
+}
+.main-toc ul,
+.sidebar ul {
+  list-style: none;
+  padding-left: 0;
+  margin: 0;
+  padding-bottom: 80px;
+}
+.main-toc ul::after,
+.sidebar ul::after {
+  content: "";
+  display: block;
+  height: 80px;
+}
+.main-toc li,
+.sidebar li {
+  margin: 0.25em 0;
+}
+.main-toc a,
+.sidebar a {
+  color: rgba(255, 255, 255, 0.85);
+  text-decoration: none;
+  display: block;
+  padding: 6px 12px;
+  border-radius: 4px;
+  transition: all 0.15s ease;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.main-toc a:hover,
+.sidebar a:hover {
+  background: #334155;
+  color: #fff;
+}
+.sidebar a.active {
+  color: #0ea5e9;
+  font-weight: 500;
+}
+/* Body margin for sidebar */
+body {
+  margin-left: 270px;
+}
+/* Hamburger menu button */
+.hamburger-menu {
+  display: none;
+  position: fixed;
+  top: 12px;
+  left: 12px;
+  z-index: 200;
+  background: #1e293b;
+  border: 2px solid rgba(255, 255, 255, 0.1);
+  border-radius: 6px;
+  padding: 10px;
+  cursor: pointer;
+  color: rgba(255, 255, 255, 0.9);
+  font-size: 20px;
+  line-height: 1;
+  width: 44px;
+  height: 44px;
+  align-items: center;
+  justify-content: center;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.2);
+  transition: all 0.2s ease;
+  opacity: 0.2;
+}
+.hamburger-menu:hover {
+  background: #334155;
+  color: #fff;
+  opacity: 1;
+}
+/* Move hamburger to the right of the sidebar when menu is open */
+.hamburger-menu.active {
+  left: calc(
+    250px + 12px
+  ); /* Position just to the right of sidebar (max-width 250px + 12px padding) */
+}
+.hamburger-menu.active {
+  background: #0ea5e9;
+}
+.hamburger-menu::before {
+  content: "☰";
+}
+.hamburger-menu.active::before {
+  content: "✕";
+}
+/* Mobile menu overlay */
+.mobile-menu-overlay {
+  display: none;
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: rgba(0, 0, 0, 0.5);
+  z-index: 150;
+  opacity: 0;
+  visibility: hidden;
+  transition: opacity 0.3s ease, visibility 0.3s ease;
+}
+.mobile-menu-overlay.active {
+  opacity: 1;
+  visibility: visible;
+}
+/* Page TOC */
+.page-toc {
+  background: #f9f9f9;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  padding: 1rem;
+  margin: 1.5rem 0;
+}
+.page-toc ul {
+  list-style: none;
+  padding-left: 0;
+  margin: 0;
+}
+.page-toc > ul {
+  padding-left: 0;
+}
+.page-toc li {
+  margin: 0.25em 0;
+}
+.page-toc a {
+  color: #0066cc;
+  text-decoration: none;
+  display: block;
+  padding: 0.25em 0.5em;
+  border-radius: 3px;
+}
+.page-toc a:hover {
+  background: #e0e0e0;
+  color: #004499;
+}
+.page-toc ul ul {
+  list-style: none;
+  padding-left: 1.5em;
+  margin-top: 0.25em;
+  margin-left: 0;
+}
+.page-toc ul ul ul {
+  padding-left: 1.5em;
+}
+.page-toc ul ul a {
+  font-size: 0.9em;
+  color: #555;
+}
+.page-toc ul ul ul a {
+  font-size: 0.85em;
+  color: #666;
+}
+/* Floating TOC */
+.floating-toc {
+  position: fixed;
+  top: 0;
+  left: 270px;
+  right: 0;
+  z-index: 50;
+  opacity: 0;
+  visibility: hidden;
+  transition: opacity 0.2s ease, visibility 0.2s ease;
+  pointer-events: none;
+  display: flex;
+  justify-content: flex-end;
+  padding-right: 2rem;
+}
+.floating-toc.visible {
+  opacity: 1;
+  visibility: visible;
+  pointer-events: auto;
+}
+.floating-toc-container {
+  background: rgba(255, 255, 255, 0.95);
+  backdrop-filter: blur(10px);
+  border-bottom: 1px solid #ddd;
+  border-radius: 0 0 12px 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+  width: fit-content;
+  max-width: 400px;
+  min-width: 200px;
+  overflow: hidden;
+  transition: max-height 0.3s ease;
+}
+.floating-toc-header {
+  padding: 8px 16px;
+  cursor: pointer;
+  user-select: none;
+  font-size: 14px;
+  font-weight: 500;
+  color: #1e293b;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+.floating-toc-header:hover {
+  background: rgba(0, 0, 0, 0.02);
+}
+.floating-toc-content {
+  max-height: 0;
+  overflow: hidden;
+  transition: max-height 0.3s ease;
+}
+.floating-toc-container:hover .floating-toc-content {
+  max-height: 70vh;
+  overflow-y: auto;
+}
+.floating-toc-content ul {
+  list-style: none;
+  padding: 8px 16px 16px;
+  margin: 0;
+}
+.floating-toc-content li {
+  margin: 0.1em 0;
+}
+.floating-toc-content a {
+  color: #0066cc;
+  text-decoration: none;
+  display: block;
+  padding: 0.2em 0.5em;
+  border-radius: 4px;
+  font-size: 13px;
+  transition: background 0.15s ease;
+}
+.floating-toc-content a:hover {
+  background: #e0e0e0;
+  color: #004499;
+}
+.floating-toc-content ul ul {
+  padding-left: 1.2em;
+  margin-top: 0;
+  margin-bottom: 0;
+}
+.floating-toc-content ul ul ul {
+  margin-top: 0;
+  margin-bottom: 0;
+}
+.floating-toc-content ul ul a {
+  font-size: 12px;
+  color: #555;
+}
+.floating-toc-content ul ul ul a {
+  font-size: 11px;
+  color: #666;
+}
+/* Smooth scrolling */
+html {
+  scroll-behavior: smooth;
+}
+/* Code blocks */
+code {
+  background: #f0f0f0;
+  padding: 0.2em 0.4em;
+  border-radius: 3px;
+  font-family: "Monaco", "Menlo", "Ubuntu Mono", monospace;
+  font-size: 0.9em;
+  margin: 0 0.1em;
+}
+pre {
+  background: #f5f5f5;
+  padding: 1rem;
+  overflow-x: auto;
+  border-radius: 4px;
+  margin: 1em 0;
+}
+pre code {
+  background: none;
+  padding: 0;
+  margin: 0;
+}
+/* Rouge syntax highlighting - GitHub theme, scoped to .highlight containers */
+.highlight {
+  color: #24292e;
+}
+.highlight .c {
+  color: #6a737d;
+  font-style: italic;
+} /* Comment */
+.highlight .err {
+  color: #a61717;
+  background-color: #e3d2d2;
+} /* Error */
+.highlight .k {
+  color: #d73a49;
+  font-weight: bold;
+} /* Keyword */
+.highlight .l {
+  color: #032f62;
+} /* Literal */
+.highlight .n {
+  color: #24292e;
+} /* Name */
+.highlight .o {
+  color: #d73a49;
+} /* Operator */
+.highlight .p {
+  color: #24292e;
+} /* Punctuation */
+.highlight .cm {
+  color: #6a737d;
+  font-style: italic;
+} /* Comment.Multiline */
+.highlight .cp {
+  color: #6a737d;
+  font-weight: bold;
+} /* Comment.Preproc */
+.highlight .c1 {
+  color: #6a737d;
+  font-style: italic;
+} /* Comment.Single */
+.highlight .cs {
+  color: #6a737d;
+  font-weight: bold;
+  font-style: italic;
+} /* Comment.Special */
+.highlight .gd {
+  color: #24292e;
+  background-color: #ffeef0;
+} /* Generic.Deleted */
+.highlight .ge {
+  color: #24292e;
+  font-style: italic;
+} /* Generic.Emph */
+.highlight .gr {
+  color: #aa0000;
+} /* Generic.Error */
+.highlight .gh {
+  color: #999999;
+  font-weight: bold;
+} /* Generic.Heading */
+.highlight .gi {
+  color: #24292e;
+  background-color: #f0fff4;
+} /* Generic.Inserted */
+.highlight .go {
+  color: #888888;
+} /* Generic.Output */
+.highlight .gp {
+  color: #555555;
+} /* Generic.Prompt */
+.highlight .gs {
+  font-weight: bold;
+} /* Generic.Strong */
+.highlight .gu {
+  color: #aaaaaa;
+} /* Generic.Subheading */
+.highlight .gt {
+  color: #aa0000;
+} /* Generic.Traceback */
+.highlight .kc {
+  color: #d73a49;
+  font-weight: bold;
+} /* Keyword.Constant */
+.highlight .kd {
+  color: #d73a49;
+  font-weight: bold;
+} /* Keyword.Declaration */
+.highlight .kn {
+  color: #d73a49;
+  font-weight: bold;
+} /* Keyword.Namespace */
+.highlight .kp {
+  color: #d73a49;
+  font-weight: bold;
+} /* Keyword.Pseudo */
+.highlight .kr {
+  color: #d73a49;
+  font-weight: bold;
+} /* Keyword.Reserved */
+.highlight .kt {
+  color: #d73a49;
+  font-weight: bold;
+} /* Keyword.Type */
+.highlight .ld {
+  color: #032f62;
+} /* Literal.Date */
+.highlight .m {
+  color: #005cc5;
+} /* Literal.Number */
+.highlight .s {
+  color: #032f62;
+} /* Literal.String */
+.highlight .na {
+  color: #6f42c1;
+} /* Name.Attribute */
+.highlight .nb {
+  color: #005cc5;
+} /* Name.Builtin */
+.highlight .nc {
+  color: #6f42c1;
+  font-weight: bold;
+} /* Name.Class */
+.highlight .no {
+  color: #005cc5;
+} /* Name.Constant */
+.highlight .nd {
+  color: #6f42c1;
+  font-weight: bold;
+} /* Name.Decorator */
+.highlight .ni {
+  color: #800080;
+} /* Name.Entity */
+.highlight .ne {
+  color: #990000;
+  font-weight: bold;
+} /* Name.Exception */
+.highlight .nf {
+  color: #6f42c1;
+} /* Name.Function */
+.highlight .nl {
+  color: #990000;
+} /* Name.Label */
+.highlight .nn {
+  color: #555555;
+} /* Name.Namespace */
+.highlight .nx {
+  color: #6f42c1;
+} /* Name.Other */
+.highlight .py {
+  color: #990000;
+} /* Name.Property */
+.highlight .nt {
+  color: #22863a;
+} /* Name.Tag */
+.highlight .nv {
+  color: #e36209;
+} /* Name.Variable */
+.highlight .ow {
+  color: #d73a49;
+  font-weight: bold;
+} /* Operator.Word */
+.highlight .w {
+  color: #bbbbbb;
+} /* Text.Whitespace */
+.highlight .mf {
+  color: #005cc5;
+} /* Literal.Number.Float */
+.highlight .mh {
+  color: #005cc5;
+} /* Literal.Number.Hex */
+.highlight .mi {
+  color: #005cc5;
+} /* Literal.Number.Integer */
+.highlight .mo {
+  color: #005cc5;
+} /* Literal.Number.Oct */
+.highlight .sb {
+  color: #032f62;
+} /* Literal.String.Backtick */
+.highlight .sc {
+  color: #032f62;
+} /* Literal.String.Char */
+.highlight .sd {
+  color: #032f62;
+} /* Literal.String.Doc */
+.highlight .s2 {
+  color: #032f62;
+} /* Literal.String.Double */
+.highlight .se {
+  color: #032f62;
+} /* Literal.String.Escape */
+.highlight .sh {
+  color: #032f62;
+} /* Literal.String.Heredoc */
+.highlight .si {
+  color: #032f62;
+} /* Literal.String.Interpol */
+.highlight .sx {
+  color: #032f62;
+} /* Literal.String.Other */
+.highlight .sr {
+  color: #22863a;
+} /* Literal.String.Regex */
+.highlight .s1 {
+  color: #032f62;
+} /* Literal.String.Single */
+.highlight .ss {
+  color: #032f62;
+} /* Literal.String.Symbol */
+.highlight .bp {
+  color: #005cc5;
+} /* Name.Builtin.Pseudo */
+.highlight .vc {
+  color: #e36209;
+} /* Name.Variable.Class */
+.highlight .vg {
+  color: #e36209;
+} /* Name.Variable.Global */
+.highlight .vi {
+  color: #e36209;
+} /* Name.Variable.Instance */
+.highlight .il {
+  color: #005cc5;
+} /* Literal.Number.Integer.Long */
+/* Additional Rouge token classes that may be used */
+.highlight .token {
+  color: #5670a0;
+}
+.highlight .token.list {
+  color: #546e9f;
+}
+.highlight .token.punctuation {
+  color: #3e8dad;
+}
+.highlight .token.list.punctuation {
+  color: #e05b78;
+}
+.highlight .token.content {
+  padding: 0;
+}
+/* Nested lists in page content */
+ul ul,
+ol ol,
+ul ol,
+ol ul {
+  padding-left: 1.5em;
+  margin-top: 0.25em;
+}
+/* Page footer */
+.page-footer {
+  background: #f5f5f5;
+  border-top: 1px solid #ddd;
+  padding: 1.5rem;
+  margin-top: 3rem;
+  color: #666;
+  font-size: 0.9em;
+}
+.page-footer p {
+  margin: 0.5em 0;
+}
+.page-footer a {
+  color: #0066cc;
+  text-decoration: none;
+}
+.page-footer a:hover {
+  text-decoration: underline;
+}
+/* Mobile responsive */
+@media (max-width: 768px) {
+  .hamburger-menu {
+    display: flex;
+  }
+  .main-toc,
+  .sidebar {
+    transform: translateX(-100%);
+    z-index: 175;
+  }
+  .main-toc.mobile-open,
+  .sidebar.mobile-open {
+    transform: translateX(0);
+  }
+  body {
+    margin-left: 0;
+  }
+  .floating-toc {
+    left: 0;
+  }
+}
+</style></head>
+  <body>
+<div class="floating-toc" id="floating-toc">
+  <div class="floating-toc-container">
+    <div class="floating-toc-header">
+      <span>Table of Contents 🔻</span>
+    </div>
+    <div class="floating-toc-content" id="floating-toc-content">
+      <!-- Content will be populated by JavaScript -->
+    </div>
+  </div>
+</div>
+<button class="hamburger-menu" id="hamburger-menu" aria-label="Toggle navigation"></button>
+<div class="mobile-menu-overlay" id="mobile-menu-overlay"></div>
+<nav class="main-toc"><ul><li><a href="Home.html">Home</a></li><li><a href="Getting-Started.html">Getting Started</a></li><li><a href="Installation.html">Installation</a></li><li><a href="Usage.html">Usage</a></li><li><a href="Syntax.html">Syntax</a></li><li><a href="Inline-Attribute-Lists.html">Inline Attribute Lists</a></li><li><a href="Modes.html">Modes</a></li><li><a href="Command-Line-Options.html">Command Line Options</a></li><li><a href="Multi-File-Documents.html">Multi-file Documents</a></li><li><a href="Citations.html">Citations</a></li><li><a href="Metadata-Transforms.html">Metadata Transforms</a></li><li><a href="Pandoc-Integration.html">Integrating with Pandoc</a></li><li><a href="Header-IDs.html">Header IDs</a></li><li><a href="C-API.html">C API</a></li><li><a href="Xcode-Integration.html">Xcode Integration</a></li><li><a href="Examples.html">Examples</a></li><li><a href="Plugins.html">Plugins</a></li><li><a href="Troubleshooting.html">Troubleshooting</a></li><li><a href="Credits.html">Credits</a></li></ul></nav>
+    <h1 id="xcode-integration">
+      Xcode Integration
+    </h1>
+<nav class="page-toc" id="page-toc-top"><ul><li><a href="#xcode-integration">Xcode Integration</a><ul><li><a href="#production-readiness">Production Readiness</a></li><li><a href="#swift-package-manager-spm-recommended">Swift Package Manager (SPM) - Recommended</a><ul><li><a href="#adding-apex-via-spm">Adding Apex via SPM</a></li><li><a href="#using-apex-in-your-code">Using Apex in Your Code</a></li><li><a href="#platform-support">Platform Support</a></li><li><a href="#spm-benefits">SPM Benefits</a></li></ul></li><li><a href="#framework-build-alternative">Framework Build (Alternative)</a></li><li><a href="#adding-to-xcode-project">Adding to Xcode Project</a><ul><li><a href="#method-1-swift-package-manager-recommended">Method 1: Swift Package Manager (Recommended)</a></li><li><a href="#method-2-framework-reference">Method 2: Framework Reference</a></li><li><a href="#method-3-cmake-integration">Method 3: CMake Integration</a></li></ul></li><li><a href="#objective-c-wrapper">Objective-C Wrapper</a><ul><li><a href="#basic-usage">Basic Usage</a></li><li><a href="#api">API</a></li><li><a href="#convenience-methods">Convenience Methods</a><ul><li><a href="#standalone-html-documents">Standalone HTML Documents</a></li><li><a href="#pretty-printed-html">Pretty-Printed HTML</a></li><li><a href="#dictionary-based-options">Dictionary-Based Options</a></li><li><a href="#swift-friendly-convenience-method">Swift-Friendly Convenience Method</a></li><li><a href="#instance-methods">Instance Methods</a></li></ul></li></ul></li><li><a href="#mode-constants">Mode Constants</a></li><li><a href="#direct-c-api-usage">Direct C API Usage</a></li><li><a href="#integration-example">Integration Example</a><ul><li><a href="#adding-to-marked">Adding to Marked</a></li></ul></li><li><a href="#build-settings">Build Settings</a><ul><li><a href="#header-search-paths">Header Search Paths</a></li><li><a href="#framework-search-paths">Framework Search Paths</a></li><li><a href="#other-linker-flags">Other Linker Flags</a></li><li><a href="#swift-api-support">Swift API Support</a></li></ul></li><li><a href="#swift-integration">Swift Integration</a><ul><li><a href="#idiomatic-swift-api-recommended">Idiomatic Swift API (Recommended)</a></li><li><a href="#apexmode-enum">ApexMode Enum</a></li><li><a href="#apexoptions-struct">ApexOptions Struct</a></li><li><a href="#objective-c-bridge-alternative">Objective-C Bridge (Alternative)</a></li></ul></li><li><a href="#troubleshooting">Troubleshooting</a><ul><li><a href="#swift-package-manager-issues">Swift Package Manager Issues</a></li><li><a href="#framework-not-found">Framework Not Found</a></li><li><a href="#linker-errors">Linker Errors</a></li><li><a href="#runtime-errors">Runtime Errors</a></li></ul></li><li><a href="#performance">Performance</a></li><li><a href="#module-map">Module Map</a></li><li><a href="#comparison-of-integration-methods">Comparison of Integration Methods</a></li><li><a href="#related">Related</a></li></ul></li></ul></nav>
+    <p>
+      This guide covers integrating Apex into Xcode projects for macOS and iOS applications.
+    </p>
+    <h2 id="production-readiness">
+      Production Readiness
+    </h2>
+    <p>
+<strong>      Important:</strong> Apex is currently in a pre-1.0 development stage. The API and implementation are still evolving, and breaking changes may occur between versions. Apex should only be used for testing and development purposes at this time.
+    </p>
+    <p>
+      Once Apex reaches version 1.0, the project will follow <a href="https://semver.org/">Semantic Versioning</a>. This means:
+    </p>
+    <ul>
+      <li>
+<strong>        Major versions</strong> (1.0, 2.0, etc.) may include breaking API changes
+      </li>
+      <li>
+<strong>        Minor versions</strong> (1.1, 1.2, etc.) will add new features while maintaining backward compatibility
+      </li>
+      <li>
+<strong>        Patch versions</strong> (1.0.1, 1.0.2, etc.) will only include bug fixes and will maintain full backward compatibility
+      </li>
+    </ul>
+    <p>
+      For production use, please wait for the stable 1.0 release. Until then, please report any issues or provide feedback to help shape the final API.
+    </p>
+    <h2 id="swift-package-manager-spm-recommended">
+      Swift Package Manager (SPM) - Recommended
+    </h2>
+    <p>
+      The easiest way to integrate Apex into your Xcode project is using Swift Package Manager.
+    </p>
+    <h3 id="adding-apex-via-spm">
+      Adding Apex via SPM
+    </h3>
+    <ol>
+      <li>
+        In Xcode, select your project in the navigator
+      </li>
+      <li>
+        Select your target
+      </li>
+      <li>
+        Go to the “Package Dependencies” tab
+      </li>
+      <li>
+        Click the “+” button
+      </li>
+      <li>
+        Enter the repository URL: <code>https://github.com/ApexMarkdown/apex</code>
+      </li>
+      <li>
+        Select the version or branch you want to use
+      </li>
+      <li>
+        Click “Add Package”
+      </li>
+      <li>
+        Select the “Apex” library product
+      </li>
+      <li>
+        Click “Add Package”
+      </li>
+    </ol>
+    <h3 id="using-apex-in-your-code">
+      Using Apex in Your Code
+    </h3>
+    <p>
+      Once added via SPM, simply import and use:
+    </p>
+<pre><code class="highlight language-swift"><span class="kd">import</span> <span class="kt">Apex</span>
+ <span class="kt">Basic</span> <span class="n">usage</span>
+<span class="k">let</span> <span class="nv">markdown</span> <span class="o">=</span> <span class="s">"# Hello World"</span>
+<span class="k">let</span> <span class="nv">html</span> <span class="o">=</span> <span class="n">markdown</span><span class="o">.</span><span class="nf">apexHTML</span><span class="p">()</span>
+ <span class="kt">With</span> <span class="n">mode</span>
+<span class="k">let</span> <span class="nv">html2</span> <span class="o">=</span> <span class="n">markdown</span><span class="o">.</span><span class="nf">apexHTML</span><span class="p">(</span><span class="nv">mode</span><span class="p">:</span> <span class="o">.</span><span class="n">gfm</span><span class="p">)</span>
+ <span class="kt">With</span> <span class="n">options</span>
+<span class="k">var</span> <span class="nv">options</span> <span class="o">=</span> <span class="kt">ApexOptions</span><span class="p">()</span>
+<span class="n">options</span><span class="o">.</span><span class="n">pretty</span> <span class="o">=</span> <span class="kc">true</span>
+<span class="n">options</span><span class="o">.</span><span class="n">generateHeaderIDs</span> <span class="o">=</span> <span class="kc">true</span>
+<span class="k">let</span> <span class="nv">html3</span> <span class="o">=</span> <span class="n">markdown</span><span class="o">.</span><span class="nf">apexHTML</span><span class="p">(</span><span class="nv">mode</span><span class="p">:</span> <span class="o">.</span><span class="n">unified</span><span class="p">,</span> <span class="nv">options</span><span class="p">:</span> <span class="n">options</span><span class="p">)</span>
+</code></pre>
+  <h3 id="platform-support">
+    Platform Support
+  </h3>
+  <ul>
+    <li>
+<strong>      macOS</strong>: 10.13+ (High Sierra)
+    </li>
+    <li>
+<strong>      iOS</strong>: 11.0+
+    </li>
+  </ul>
+  <h3 id="spm-benefits">
+    SPM Benefits
+  </h3>
+  <ul>
+    <li>
+      Automatic dependency management
+    </li>
+    <li>
+      No manual framework embedding
+    </li>
+    <li>
+      Works with both macOS and iOS
+    </li>
+    <li>
+      Easy version updates
+    </li>
+    <li>
+      Integrated with Xcode’s build system
+    </li>
+  </ul>
+  <h2 id="framework-build-alternative">
+    Framework Build (Alternative)
+  </h2>
+  <p>
+    Apex can also be built as a framework for manual integration:
+  </p>
+<pre><code class="highlight language-bash"><span class="nb">cd </span>apex
+<span class="nb">mkdir </span>build <span class="o">&amp;&amp;</span> <span class="nb">cd </span>build
+cmake <span class="nt">-DBUILD_FRAMEWORK</span><span class="o">=</span>ON ..
+make
+</code></pre>
+<p>
+  The framework will be at <code>build/Apex.framework</code>.
+</p>
+<h2 id="adding-to-xcode-project">
+  Adding to Xcode Project
+</h2>
+<h3 id="method-1-swift-package-manager-recommended">
+  Method 1: Swift Package Manager (Recommended)
+</h3>
+<p>
+  See the SPM section above for the easiest integration method.
+</p>
+<h3 id="method-2-framework-reference">
+  Method 2: Framework Reference
+</h3>
+<ol>
+  <li>
+    Drag <code>Apex.framework</code> into your Xcode project
+  </li>
+  <li>
+    Add to “Frameworks, Libraries, and Embedded Content”
+  </li>
+  <li>
+    Set “Embed &amp; Sign” for the framework
+  </li>
+</ol>
+<h3 id="method-3-cmake-integration">
+  Method 3: CMake Integration
+</h3>
+<p>
+  If your project uses CMake:
+</p>
+<pre><code class="highlight language-cmake"><span class="nb">add_subdirectory</span><span class="p">(</span>apex<span class="p">)</span>
+<span class="nb">target_link_libraries</span><span class="p">(</span>your_app Apex<span class="p">)</span>
+</code></pre>
+<h2 id="objective-c-wrapper">
+  Objective-C Wrapper
+</h2>
+<p>
+  Apex includes an Objective-C wrapper for easy integration:
+</p>
+<p>
+<strong>  Files:</strong>
+</p>
+<ul>
+  <li>
+<code>apex/objc/NSString+Apex.h</code>
+  </li>
+  <li>
+<code>apex/objc/NSString+Apex.m</code>
+  </li>
+</ul>
+<h3 id="basic-usage">
+  Basic Usage
+</h3>
+<pre><code class="highlight language-objective-c"><span class="cp">#import "NSString+Apex.h"
+</span>
+ <span class="n">Convert</span> <span class="n">with</span> <span class="k">default</span> <span class="n">unified</span> <span class="n">mode</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">html</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSString</span> <span class="nf">convertWithApex</span><span class="p">:</span><span class="n">markdownText</span><span class="p">];</span>
+ <span class="n">Convert</span> <span class="n">with</span> <span class="n">specific</span> <span class="n">mode</span> <span class="n">using</span> <span class="n">constants</span> <span class="p">(</span><span class="n">recommended</span><span class="p">)</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">gfmHtml</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSString</span> <span class="nf">convertWithApex</span><span class="p">:</span><span class="n">markdownText</span> <span class="nf">mode</span><span class="p">:</span><span class="n">ApexModeGFM</span><span class="p">];</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">mmdHtml</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSString</span> <span class="nf">convertWithApex</span><span class="p">:</span><span class="n">markdownText</span> <span class="nf">mode</span><span class="p">:</span><span class="n">ApexModeMultiMarkdown</span><span class="p">];</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">kramdownHtml</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSString</span> <span class="nf">convertWithApex</span><span class="p">:</span><span class="n">markdownText</span> <span class="nf">mode</span><span class="p">:</span><span class="n">ApexModeKramdown</span><span class="p">];</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">commonmarkHtml</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSString</span> <span class="nf">convertWithApex</span><span class="p">:</span><span class="n">markdownText</span> <span class="nf">mode</span><span class="p">:</span><span class="n">ApexModeCommonmark</span><span class="p">];</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">unifiedHtml</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSString</span> <span class="nf">convertWithApex</span><span class="p">:</span><span class="n">markdownText</span> <span class="nf">mode</span><span class="p">:</span><span class="n">ApexModeUnified</span><span class="p">];</span>
+ <span class="n">String</span> <span class="n">literals</span> <span class="n">also</span> <span class="n">work</span> <span class="p">(</span><span class="k">for</span> <span class="n">backward</span> <span class="n">compatibility</span><span class="p">)</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">gfmHtml2</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSString</span> <span class="nf">convertWithApex</span><span class="p">:</span><span class="n">markdownText</span> <span class="nf">mode</span><span class="p">:</span><span class="s">@"gfm"</span><span class="p">];</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">mmdHtml2</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSString</span> <span class="nf">convertWithApex</span><span class="p">:</span><span class="n">markdownText</span> <span class="nf">mode</span><span class="p">:</span><span class="s">@"multimarkdown"</span><span class="p">];</span>
+</code></pre>
+<h3 id="api">
+  API
+</h3>
+<pre><code class="highlight language-objective-c"> <span class="n">Mode</span> <span class="n">constants</span>
+<span class="k">extern</span> <span class="n">NSString</span> <span class="o">*</span> <span class="k">const</span> <span class="n">ApexModeCommonmark</span><span class="p">;</span>
+<span class="k">extern</span> <span class="n">NSString</span> <span class="o">*</span> <span class="k">const</span> <span class="n">ApexModeGFM</span><span class="p">;</span>
+<span class="k">extern</span> <span class="n">NSString</span> <span class="o">*</span> <span class="k">const</span> <span class="n">ApexModeMultiMarkdown</span><span class="p">;</span>
+<span class="k">extern</span> <span class="n">NSString</span> <span class="o">*</span> <span class="k">const</span> <span class="n">ApexModeKramdown</span><span class="p">;</span>
+<span class="k">extern</span> <span class="n">NSString</span> <span class="o">*</span> <span class="k">const</span> <span class="n">ApexModeUnified</span><span class="p">;</span>
+<span class="k">@interface</span> <span class="nc">NSString</span> <span class="p">(</span><span class="nl">Apex</span><span class="p">)</span>
+ <span class="n">Basic</span> <span class="n">conversion</span> <span class="n">methods</span>
+<span class="k">+</span> <span class="p">(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nf">convertWithApex</span><span class="p">:(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nv">markdown</span><span class="p">;</span>
+<span class="k">+</span> <span class="p">(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nf">convertWithApex</span><span class="p">:(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nv">markdown</span> <span class="nf">mode</span><span class="p">:(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nv">mode</span><span class="p">;</span>
+ <span class="n">Standalone</span> <span class="n">HTML</span> <span class="n">document</span> <span class="n">generation</span>
+<span class="k">+</span> <span class="p">(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nf">convertWithApex</span><span class="p">:(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nv">markdown</span>
+                         <span class="nf">mode</span><span class="p">:(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nv">mode</span>
+                   <span class="nf">standalone</span><span class="p">:(</span><span class="n">BOOL</span><span class="p">)</span><span class="nv">standalone</span>
+                    <span class="nf">stylesheet</span><span class="p">:(</span><span class="n">NSString</span> <span class="o">*</span> <span class="n">_Nullable</span><span class="p">)</span><span class="nv">stylesheetPath</span>
+                         <span class="nf">title</span><span class="p">:(</span><span class="n">NSString</span> <span class="o">*</span> <span class="n">_Nullable</span><span class="p">)</span><span class="nv">title</span><span class="p">;</span>
+ <span class="n">Pretty</span><span class="k">-</span><span class="n">printed</span> <span class="n">HTML</span> <span class="n">output</span>
+<span class="k">+</span> <span class="p">(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nf">convertWithApex</span><span class="p">:(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nv">markdown</span>
+                         <span class="nf">mode</span><span class="p">:(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nv">mode</span>
+                        <span class="nf">pretty</span><span class="p">:(</span><span class="n">BOOL</span><span class="p">)</span><span class="nv">pretty</span><span class="p">;</span>
+ <span class="n">Dictionary</span><span class="k">-</span><span class="n">based</span> <span class="n">options</span> <span class="n">configuration</span>
+<span class="k">+</span> <span class="p">(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nf">convertWithApex</span><span class="p">:(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nv">markdown</span>
+                         <span class="nf">mode</span><span class="p">:(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nv">mode</span>
+                    <span class="nf">options</span><span class="p">:(</span><span class="n">NSDictionary</span><span class="o">&lt;</span><span class="n">NSString</span> <span class="o">*</span><span class="p">,</span> <span class="n">id</span><span class="o">&gt;</span> <span class="o">*</span> <span class="n">_Nullable</span><span class="p">)</span><span class="nv">options</span><span class="p">;</span>
+ <span class="n">Swift</span><span class="k">-</span><span class="n">friendly</span> <span class="n">convenience</span> <span class="n">method</span> <span class="n">with</span> <span class="n">common</span> <span class="n">options</span>
+<span class="k">+</span> <span class="p">(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nf">convertWithApex</span><span class="p">:(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nv">markdown</span>
+                         <span class="nf">mode</span><span class="p">:(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nv">mode</span>
+              <span class="nf">generateHeaderIDs</span><span class="p">:(</span><span class="n">BOOL</span><span class="p">)</span><span class="nv">generateHeaderIDs</span>
+                    <span class="nf">hardBreaks</span><span class="p">:(</span><span class="n">BOOL</span><span class="p">)</span><span class="nv">hardBreaks</span>
+                        <span class="nf">pretty</span><span class="p">:(</span><span class="n">BOOL</span><span class="p">)</span><span class="nv">pretty</span><span class="p">;</span>
+ <span class="n">Instance</span> <span class="n">methods</span> <span class="k">for</span> <span class="n">convenient</span> <span class="n">usage</span>
+<span class="k">-</span> <span class="p">(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="n">apexHTML</span><span class="p">;</span>
+<span class="k">-</span> <span class="p">(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nf">apexHTMLWithMode</span><span class="p">:(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nv">mode</span><span class="p">;</span>
+<span class="k">@end</span>
+</code></pre>
+<p>
+<strong>  Parameters:</strong>
+</p>
+<ul>
+  <li>
+<code>markdown</code> - Input Markdown text
+  </li>
+  <li>
+<code>mode</code> - Processor mode: Use <code>ApexMode*</code> constants (recommended) or string literals:
+    <ul>
+      <li>
+<code>ApexModeCommonmark</code> or <code>@&quot;commonmark&quot;</code> - Pure CommonMark specification
+      </li>
+      <li>
+<code>ApexModeGFM</code> or <code>@&quot;gfm&quot;</code> - GitHub Flavored Markdown
+      </li>
+      <li>
+<code>ApexModeMultiMarkdown</code> or <code>@&quot;multimarkdown&quot;</code> / <code>@&quot;mmd&quot;</code> - MultiMarkdown compatibility
+      </li>
+      <li>
+<code>ApexModeKramdown</code> or <code>@&quot;kramdown&quot;</code> - Kramdown compatibility
+      </li>
+      <li>
+<code>ApexModeUnified</code> or <code>@&quot;unified&quot;</code> - All features enabled (default)
+      </li>
+    </ul>
+  </li>
+</ul>
+<p>
+<strong>  Returns:</strong> HTML string (autoreleased)
+</p>
+<p>
+<strong>  Note:</strong> Using the <code>ApexMode*</code> constants is recommended to avoid typos and provides autocomplete support in Xcode. String literals are still supported for backward compatibility.
+</p>
+<h3 id="convenience-methods">
+  Convenience Methods
+</h3>
+<p>
+  Apex provides additional convenience methods for common use cases:
+</p>
+<h4 id="standalone-html-documents">
+  Standalone HTML Documents
+</h4>
+<p>
+  Generate complete HTML5 documents with stylesheet and title:
+</p>
+<pre><code class="highlight language-objective-c"> <span class="n">Generate</span> <span class="n">standalone</span> <span class="n">HTML</span> <span class="n">document</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">html</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSString</span> <span class="nf">convertWithApex</span><span class="p">:</span><span class="n">markdown</span>
+                                     <span class="nl">mode:</span><span class="n">ApexModeUnified</span>
+                               <span class="nl">standalone:</span><span class="nb">YES</span>
+                                <span class="nl">stylesheet:</span><span class="s">@"style.css"</span>
+                                     <span class="nl">title:</span><span class="s">@"My Document"</span><span class="p">];</span>
+ <span class="n">Without</span> <span class="n">stylesheet</span> <span class="n">or</span> <span class="n">title</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">html2</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSString</span> <span class="nf">convertWithApex</span><span class="p">:</span><span class="n">markdown</span>
+                                       <span class="nl">mode:</span><span class="n">ApexModeGFM</span>
+                                 <span class="nl">standalone:</span><span class="nb">YES</span>
+                                  <span class="nl">stylesheet:</span><span class="nb">nil</span>
+                                       <span class="nl">title:</span><span class="nb">nil</span><span class="p">];</span>
+</code></pre>
+<h4 id="pretty-printed-html">
+  Pretty-Printed HTML
+</h4>
+<p>
+  Generate formatted HTML with indentation:
+</p>
+<pre><code class="highlight language-objective-c"> <span class="n">Pretty</span><span class="k">-</span><span class="n">print</span> <span class="n">HTML</span> <span class="n">output</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">html</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSString</span> <span class="nf">convertWithApex</span><span class="p">:</span><span class="n">markdown</span>
+                                     <span class="nl">mode:</span><span class="n">ApexModeUnified</span>
+                                    <span class="nl">pretty:</span><span class="nb">YES</span><span class="p">];</span>
+</code></pre>
+<h4 id="dictionary-based-options">
+  Dictionary-Based Options
+</h4>
+<p>
+  Configure multiple options at once using a dictionary:
+</p>
+<pre><code class="highlight language-objective-c"> <span class="n">Configure</span> <span class="n">multiple</span> <span class="n">options</span>
+<span class="n">NSDictionary</span> <span class="o">*</span><span class="n">options</span> <span class="o">=</span> <span class="p">@{</span>
+    <span class="s">@"pretty"</span><span class="o">:</span> <span class="nb">@YES</span><span class="p">,</span>
+    <span class="s">@"standalone"</span><span class="o">:</span> <span class="nb">@YES</span><span class="p">,</span>
+    <span class="s">@"stylesheet"</span><span class="o">:</span> <span class="s">@"style.css"</span><span class="p">,</span>
+    <span class="s">@"title"</span><span class="o">:</span> <span class="s">@"My Document"</span><span class="p">,</span>
+    <span class="s">@"hardBreaks"</span><span class="o">:</span> <span class="nb">@YES</span><span class="p">,</span>
+    <span class="s">@"generateHeaderIDs"</span><span class="o">:</span> <span class="nb">@YES</span><span class="p">,</span>
+    <span class="s">@"headerAnchors"</span><span class="o">:</span> <span class="nb">@NO</span><span class="p">,</span>
+    <span class="s">@"obfuscateEmails"</span><span class="o">:</span> <span class="nb">@YES</span><span class="p">,</span>
+    <span class="s">@"embedImages"</span><span class="o">:</span> <span class="nb">@NO</span>
+<span class="p">};</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">html</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSString</span> <span class="nf">convertWithApex</span><span class="p">:</span><span class="n">markdown</span>
+                                     <span class="nl">mode:</span><span class="n">ApexModeUnified</span>
+                                   <span class="nl">options:</span><span class="n">options</span><span class="p">];</span>
+</code></pre>
+<p>
+<strong>  Supported dictionary keys:</strong>
+</p>
+<ul>
+  <li>
+<code>@&quot;pretty&quot;</code> - NSNumber (BOOL): Pretty-print HTML with indentation
+  </li>
+  <li>
+<code>@&quot;standalone&quot;</code> - NSNumber (BOOL): Generate complete HTML5 document
+  </li>
+  <li>
+<code>@&quot;stylesheet&quot;</code> - NSString: Path to CSS file to link in document head
+  </li>
+  <li>
+<code>@&quot;title&quot;</code> - NSString: Document title
+  </li>
+  <li>
+<code>@&quot;hardBreaks&quot;</code> - NSNumber (BOOL): Treat newlines as hard breaks
+  </li>
+  <li>
+<code>@&quot;generateHeaderIDs&quot;</code> - NSNumber (BOOL): Generate IDs for headers
+  </li>
+  <li>
+<code>@&quot;unsafe&quot;</code> - NSNumber (BOOL): Allow raw HTML in output
+  </li>
+  <li>
+<code>@&quot;headerAnchors&quot;</code> - NSNumber (BOOL): Generate anchor tags instead of header IDs
+  </li>
+  <li>
+<code>@&quot;obfuscateEmails&quot;</code> - NSNumber (BOOL): Obfuscate email links using HTML entities
+  </li>
+  <li>
+<code>@&quot;embedImages&quot;</code> - NSNumber (BOOL): Embed local images as base64 data URLs
+  </li>
+</ul>
+<h4 id="swift-friendly-convenience-method">
+  Swift-Friendly Convenience Method
+</h4>
+<p>
+  Combine common options in a single method call (ideal for Swift):
+</p>
+<pre><code class="highlight language-objective-c"> <span class="n">Combine</span> <span class="n">common</span> <span class="n">options</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">html</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSString</span> <span class="nf">convertWithApex</span><span class="p">:</span><span class="n">markdown</span>
+                                     <span class="nl">mode:</span><span class="n">ApexModeUnified</span>
+                          <span class="nl">generateHeaderIDs:</span><span class="nb">YES</span>
+                                <span class="nl">hardBreaks:</span><span class="nb">YES</span>
+                                    <span class="nl">pretty:</span><span class="nb">YES</span><span class="p">];</span>
+</code></pre>
+<h4 id="instance-methods">
+  Instance Methods
+</h4>
+<p>
+  Use instance methods for more natural, fluent syntax:
+</p>
+<pre><code class="highlight language-objective-c"> <span class="n">Instance</span> <span class="n">method</span> <span class="n">with</span> <span class="k">default</span> <span class="n">unified</span> <span class="n">mode</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">markdown</span> <span class="o">=</span> <span class="s">@"# Hello World"</span><span class="p">;</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">html</span> <span class="o">=</span> <span class="p">[</span><span class="n">markdown</span> <span class="nf">apexHTML</span><span class="p">];</span>
+ <span class="n">Instance</span> <span class="n">method</span> <span class="n">with</span> <span class="n">specific</span> <span class="n">mode</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">html2</span> <span class="o">=</span> <span class="p">[</span><span class="n">markdown</span> <span class="nf">apexHTMLWithMode</span><span class="p">:</span><span class="n">ApexModeGFM</span><span class="p">];</span>
+</code></pre>
+<h2 id="mode-constants">
+  Mode Constants
+</h2>
+<p>
+  Apex provides NSString constants for processor modes to avoid ambiguity and typos:
+</p>
+<pre><code class="highlight language-objective-c"> <span class="n">Available</span> <span class="n">constants</span>
+<span class="n">ApexModeCommonmark</span>      <span class="c1">// @"commonmark"</span>
+<span class="n">ApexModeGFM</span>             <span class="c1">// @"gfm"</span>
+<span class="n">ApexModeMultiMarkdown</span>   <span class="c1">// @"multimarkdown"</span>
+<span class="n">ApexModeKramdown</span>        <span class="c1">// @"kramdown"</span>
+<span class="n">ApexModeUnified</span>         <span class="c1">// @"unified"</span>
+</code></pre>
+<p>
+<strong>  Benefits:</strong>
+</p>
+<ul>
+  <li>
+<strong>    Type safety</strong>: Xcode autocomplete suggests available modes
+  </li>
+  <li>
+<strong>    No typos</strong>: Compile-time checking prevents invalid mode strings
+  </li>
+  <li>
+<strong>    Self-documenting</strong>: Constants make code more readable
+  </li>
+  <li>
+<strong>    Refactoring</strong>: Easy to find all usages if mode names change
+  </li>
+</ul>
+<p>
+<strong>  Example:</strong>
+</p>
+<pre><code class="highlight language-objective-c"> <span class="nl">Good:</span> <span class="n">Using</span> <span class="n">constants</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">html</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSString</span> <span class="nf">convertWithApex</span><span class="p">:</span><span class="n">markdown</span> <span class="nf">mode</span><span class="p">:</span><span class="n">ApexModeMultiMarkdown</span><span class="p">];</span>
+ <span class="n">Also</span> <span class="n">works</span><span class="o">:</span> <span class="n">String</span> <span class="n">literals</span> <span class="p">(</span><span class="k">for</span> <span class="n">backward</span> <span class="n">compatibility</span><span class="p">)</span>
+<span class="n">NSString</span> <span class="o">*</span><span class="n">html2</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSString</span> <span class="nf">convertWithApex</span><span class="p">:</span><span class="n">markdown</span> <span class="nf">mode</span><span class="p">:</span><span class="s">@"multimarkdown"</span><span class="p">];</span>
+</code></pre>
+<h2 id="direct-c-api-usage">
+  Direct C API Usage
+</h2>
+<p>
+  For more control, use the C API directly:
+</p>
+<pre><code class="highlight language-objective-c"><span class="cp">#include</span> <span class="cpf">&lt;Apex/apex.h&gt;</span><span class="cp">
+</span>
+<span class="k">-</span> <span class="p">(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nf">convertMarkdown</span><span class="p">:(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nv">markdown</span> <span class="p">{</span>
+    <span class="n">apex_options</span> <span class="n">opts</span> <span class="o">=</span> <span class="n">apex_options_default</span><span class="p">();</span>
+    <span class="n">opts</span><span class="p">.</span><span class="n">pretty</span> <span class="o">=</span> <span class="nb">true</span><span class="p">;</span>
+    <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">md</span> <span class="o">=</span> <span class="p">[</span><span class="n">markdown</span> <span class="nf">UTF8String</span><span class="p">];</span>
+    <span class="kt">char</span> <span class="o">*</span><span class="n">html</span> <span class="o">=</span> <span class="n">apex_markdown_to_html</span><span class="p">(</span><span class="n">md</span><span class="p">,</span> <span class="n">strlen</span><span class="p">(</span><span class="n">md</span><span class="p">),</span> <span class="o">&amp;</span><span class="n">opts</span><span class="p">);</span>
+    <span class="k">if</span> <span class="p">(</span><span class="n">html</span><span class="p">)</span> <span class="p">{</span>
+        <span class="n">NSString</span> <span class="o">*</span><span class="n">result</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSString</span> <span class="nf">stringWithUTF8String</span><span class="p">:</span><span class="n">html</span><span class="p">];</span>
+        <span class="n">apex_free_string</span><span class="p">(</span><span class="n">html</span><span class="p">);</span>
+        <span class="k">return</span> <span class="n">result</span><span class="p">;</span>
+    <span class="p">}</span>
+    <span class="k">return</span> <span class="nb">nil</span><span class="p">;</span>
+<span class="p">}</span>
+</code></pre>
+<h2 id="integration-example">
+  Integration Example
+</h2>
+<h3 id="adding-to-marked">
+  Adding to Marked
+</h3>
+<p>
+  Here’s how to add Apex support to an existing Marked-style application:
+</p>
+<p>
+<strong>  1. Add to processor selection:</strong>
+</p>
+<pre><code class="highlight language-objective-c"> <span class="n">In</span> <span class="n">MKConductorTransformer</span><span class="p">.</span><span class="n">m</span> <span class="n">or</span> <span class="n">similar</span>
+<span class="err">}</span> <span class="k">else</span> <span class="nf">if</span> <span class="p">([</span><span class="n">processor</span> <span class="nf">isEqualToString</span><span class="p">:</span><span class="s">@"Apex"</span><span class="p">])</span> <span class="p">{</span>
+    <span class="n">result</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSString</span> <span class="nf">convertWithApex</span><span class="p">:</span><span class="n">text</span><span class="p">];</span>
+<span class="p">}</span> <span class="k">else</span> <span class="nf">if</span> <span class="p">([</span><span class="n">processor</span> <span class="nf">isEqualToString</span><span class="p">:</span><span class="s">@"MultiMarkdown"</span><span class="p">])</span> <span class="p">{</span>
+    <span class="n">result</span> <span class="o">=</span> <span class="p">[</span><span class="n">NSString</span> <span class="nf">convertWithMultiMarkdown</span><span class="p">:</span><span class="n">text</span><span class="p">];</span>
+<span class="p">}</span>
+</code></pre>
+<p>
+<strong>  2. Add to preferences:</strong>
+</p>
+<pre><code class="highlight language-objective-c"> <span class="n">In</span> <span class="n">processor</span> <span class="n">dropdown</span>
+<span class="n">NSArray</span> <span class="o">*</span><span class="n">processors</span> <span class="o">=</span> <span class="p">@[</span>
+    <span class="s">@"MultiMarkdown"</span><span class="p">,</span>
+    <span class="s">@"Discount (GFM)"</span><span class="p">,</span>
+    <span class="s">@"CommonMark"</span><span class="p">,</span>
+    <span class="s">@"Kramdown"</span><span class="p">,</span>
+    <span class="s">@"Apex"</span>  <span class="c1">// Add this</span>
+<span class="p">];</span>
+</code></pre>
+<p>
+<strong>  3. Handle custom processor rules:</strong>
+</p>
+<pre><code class="highlight language-objective-c"> <span class="n">In</span> <span class="n">custom</span> <span class="n">processor</span> <span class="n">handling</span>
+<span class="err">}</span> <span class="k">else</span> <span class="nf">if</span> <span class="p">([</span><span class="n">outputString</span><span class="p">.</span><span class="n">uppercaseString</span> <span class="nf">isEqualToString</span><span class="p">:</span><span class="s">@"APEX"</span><span class="p">])</span> <span class="p">{</span>
+    <span class="p">[</span><span class="n">defaults</span> <span class="nf">setValue</span><span class="p">:</span><span class="s">@"Apex"</span> <span class="nf">forKey</span><span class="p">:</span><span class="s">@"defaultProcessor"</span><span class="p">];</span>
+<span class="p">}</span>
+</code></pre>
+<h2 id="build-settings">
+  Build Settings
+</h2>
+<h3 id="header-search-paths">
+  Header Search Paths
+</h3>
+<p>
+  Add to “Header Search Paths”:
+</p>
+<pre><code class="highlight ">$(SRCROOT)/apex/include
+</code></pre>
+<h3 id="framework-search-paths">
+  Framework Search Paths
+</h3>
+<p>
+  Add to “Framework Search Paths”:
+</p>
+<pre><code class="highlight ">$(SRCROOT)/apex/build
+</code></pre>
+<h3 id="other-linker-flags">
+  Other Linker Flags
+</h3>
+<p>
+  If using static library:
+</p>
+<pre><code class="highlight ">-L$(SRCROOT)/apex/build -lapex
+</code></pre>
+<h3 id="swift-api-support">
+  Swift API Support
+</h3>
+<p>
+  To use the idiomatic Swift API (<code>Apex.swift</code>):
+</p>
+<ol>
+  <li>
+<strong>    If using the framework:</strong> The Swift file is automatically included when you link <code>Apex.framework</code>
+  </li>
+  <li>
+<strong>    If using source files directly:</strong> Add <code>apex/objc/Apex.swift</code> to your Xcode project
+  </li>
+  <li>
+<strong>    Swift/Objective-C Bridging:</strong> Xcode will automatically create a bridging header if needed
+  </li>
+</ol>
+<p>
+  The Swift API provides:
+</p>
+<ul>
+  <li>
+    Type-safe <code>ApexMode</code> enum instead of string constants
+  </li>
+  <li>
+<code>ApexOptions</code> struct for configuration
+  </li>
+  <li>
+    Idiomatic String extensions
+  </li>
+  <li>
+    Static <code>Apex</code> converter struct
+  </li>
+</ul>
+<h2 id="swift-integration">
+  Swift Integration
+</h2>
+<p>
+  Apex provides an idiomatic Swift API wrapper (<code>Apex.swift</code>) that offers type-safe enums and structs over the Objective-C API.
+</p>
+<h3 id="idiomatic-swift-api-recommended">
+  Idiomatic Swift API (Recommended)
+</h3>
+<pre><code class="highlight language-swift"><span class="kd">import</span> <span class="kt">Foundation</span>
+ <span class="kt">Import</span> <span class="kt">Apex</span><span class="o">.</span><span class="nf">swift</span> <span class="p">(</span><span class="n">automatically</span> <span class="n">available</span> <span class="n">when</span> <span class="n">framework</span> <span class="k">is</span> <span class="n">linked</span><span class="p">)</span>
+ <span class="kt">Basic</span> <span class="n">conversion</span> <span class="n">with</span> <span class="k">default</span> <span class="n">unified</span> <span class="n">mode</span>
+<span class="k">let</span> <span class="nv">markdown</span> <span class="o">=</span> <span class="s">"# Hello World"</span>
+<span class="k">let</span> <span class="nv">html</span> <span class="o">=</span> <span class="n">markdown</span><span class="o">.</span><span class="nf">apexHTML</span><span class="p">()</span>
+ <span class="kt">With</span> <span class="n">type</span><span class="o">-</span><span class="n">safe</span> <span class="n">mode</span> <span class="kd">enum</span>
+<span class="k">let</span> <span class="nv">gfmHtml</span> <span class="o">=</span> <span class="n">markdown</span><span class="o">.</span><span class="nf">apexHTML</span><span class="p">(</span><span class="nv">mode</span><span class="p">:</span> <span class="o">.</span><span class="n">gfm</span><span class="p">)</span>
+<span class="k">let</span> <span class="nv">mmdHtml</span> <span class="o">=</span> <span class="n">markdown</span><span class="o">.</span><span class="nf">apexHTML</span><span class="p">(</span><span class="nv">mode</span><span class="p">:</span> <span class="o">.</span><span class="n">multimarkdown</span><span class="p">)</span>
+<span class="k">let</span> <span class="nv">kramdownHtml</span> <span class="o">=</span> <span class="n">markdown</span><span class="o">.</span><span class="nf">apexHTML</span><span class="p">(</span><span class="nv">mode</span><span class="p">:</span> <span class="o">.</span><span class="n">kramdown</span><span class="p">)</span>
+<span class="k">let</span> <span class="nv">commonmarkHtml</span> <span class="o">=</span> <span class="n">markdown</span><span class="o">.</span><span class="nf">apexHTML</span><span class="p">(</span><span class="nv">mode</span><span class="p">:</span> <span class="o">.</span><span class="n">commonmark</span><span class="p">)</span>
+<span class="k">let</span> <span class="nv">unifiedHtml</span> <span class="o">=</span> <span class="n">markdown</span><span class="o">.</span><span class="nf">apexHTML</span><span class="p">(</span><span class="nv">mode</span><span class="p">:</span> <span class="o">.</span><span class="n">unified</span><span class="p">)</span>
+ <span class="kt">Using</span> <span class="kt">ApexOptions</span> <span class="nf">struct</span> <span class="p">(</span><span class="n">type</span><span class="o">-</span><span class="n">safe</span><span class="p">)</span>
+<span class="k">var</span> <span class="nv">options</span> <span class="o">=</span> <span class="kt">ApexOptions</span><span class="p">()</span>
+<span class="n">options</span><span class="o">.</span><span class="n">pretty</span> <span class="o">=</span> <span class="kc">true</span>
+<span class="n">options</span><span class="o">.</span><span class="n">standalone</span> <span class="o">=</span> <span class="kc">true</span>
+<span class="n">options</span><span class="o">.</span><span class="n">stylesheet</span> <span class="o">=</span> <span class="s">"style.css"</span>
+<span class="n">options</span><span class="o">.</span><span class="n">title</span> <span class="o">=</span> <span class="s">"My Document"</span>
+<span class="n">options</span><span class="o">.</span><span class="n">generateHeaderIDs</span> <span class="o">=</span> <span class="kc">true</span>
+<span class="n">options</span><span class="o">.</span><span class="n">hardBreaks</span> <span class="o">=</span> <span class="kc">true</span>
+<span class="n">options</span><span class="o">.</span><span class="n">obfuscateEmails</span> <span class="o">=</span> <span class="kc">true</span>
+<span class="k">let</span> <span class="nv">configuredHtml</span> <span class="o">=</span> <span class="n">markdown</span><span class="o">.</span><span class="nf">apexHTML</span><span class="p">(</span><span class="nv">mode</span><span class="p">:</span> <span class="o">.</span><span class="n">unified</span><span class="p">,</span> <span class="nv">options</span><span class="p">:</span> <span class="n">options</span><span class="p">)</span>
+ <span class="kt">Or</span> <span class="n">use</span> <span class="kd">static</span> <span class="kt">Apex</span> <span class="n">converter</span>
+<span class="k">let</span> <span class="nv">html2</span> <span class="o">=</span> <span class="kt">Apex</span><span class="o">.</span><span class="nf">convert</span><span class="p">(</span><span class="n">markdown</span><span class="p">)</span>
+<span class="k">let</span> <span class="nv">html3</span> <span class="o">=</span> <span class="kt">Apex</span><span class="o">.</span><span class="nf">convert</span><span class="p">(</span><span class="n">markdown</span><span class="p">,</span> <span class="nv">mode</span><span class="p">:</span> <span class="o">.</span><span class="n">gfm</span><span class="p">)</span>
+<span class="k">let</span> <span class="nv">html4</span> <span class="o">=</span> <span class="kt">Apex</span><span class="o">.</span><span class="nf">convert</span><span class="p">(</span><span class="n">markdown</span><span class="p">,</span> <span class="nv">mode</span><span class="p">:</span> <span class="o">.</span><span class="n">unified</span><span class="p">,</span> <span class="nv">options</span><span class="p">:</span> <span class="n">options</span><span class="p">)</span>
+ <span class="kt">Standalone</span> <span class="kt">HTML</span> <span class="n">document</span>
+<span class="k">let</span> <span class="nv">standaloneHtml</span> <span class="o">=</span> <span class="n">markdown</span><span class="o">.</span><span class="nf">apexHTML</span><span class="p">(</span>
+    <span class="nv">mode</span><span class="p">:</span> <span class="o">.</span><span class="n">unified</span><span class="p">,</span>
+    <span class="nv">standalone</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
+    <span class="nv">stylesheet</span><span class="p">:</span> <span class="s">"style.css"</span><span class="p">,</span>
+    <span class="nv">title</span><span class="p">:</span> <span class="s">"My Document"</span>
+<span class="p">)</span>
+ <span class="kt">Pretty</span><span class="o">-</span><span class="n">printed</span> <span class="kt">HTML</span>
+<span class="k">let</span> <span class="nv">prettyHtml</span> <span class="o">=</span> <span class="n">markdown</span><span class="o">.</span><span class="nf">apexHTML</span><span class="p">(</span><span class="nv">pretty</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span> <span class="nv">mode</span><span class="p">:</span> <span class="o">.</span><span class="n">unified</span><span class="p">)</span>
+ <span class="kt">Common</span> <span class="n">options</span> <span class="n">combined</span>
+<span class="k">let</span> <span class="nv">commonOptionsHtml</span> <span class="o">=</span> <span class="n">markdown</span><span class="o">.</span><span class="nf">apexHTML</span><span class="p">(</span>
+    <span class="nv">mode</span><span class="p">:</span> <span class="o">.</span><span class="n">unified</span><span class="p">,</span>
+    <span class="nv">generateHeaderIDs</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
+    <span class="nv">hardBreaks</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
+    <span class="nv">pretty</span><span class="p">:</span> <span class="kc">true</span>
+<span class="p">)</span>
+</code></pre>
+<h3 id="apexmode-enum">
+  ApexMode Enum
+</h3>
+<p>
+  Type-safe processor mode enum:
+</p>
+<pre><code class="highlight language-swift"><span class="kd">public</span> <span class="kd">enum</span> <span class="kt">ApexMode</span><span class="p">:</span> <span class="kt">String</span><span class="p">,</span> <span class="kt">CaseIterable</span> <span class="p">{</span>
+    <span class="k">case</span> <span class="n">commonmark</span>
+    <span class="k">case</span> <span class="n">gfm</span>
+    <span class="k">case</span> <span class="n">multimarkdown</span>
+    <span class="k">case</span> <span class="n">kramdown</span>
+    <span class="k">case</span> <span class="n">unified</span>
+<span class="p">}</span>
+</code></pre>
+<h3 id="apexoptions-struct">
+  ApexOptions Struct
+</h3>
+<p>
+  Type-safe options configuration:
+</p>
+<pre><code class="highlight language-swift"><span class="kd">public</span> <span class="kd">struct</span> <span class="kt">ApexOptions</span> <span class="p">{</span>
+    <span class="kd">public</span> <span class="k">var</span> <span class="nv">pretty</span><span class="p">:</span> <span class="kt">Bool</span> <span class="o">=</span> <span class="kc">false</span>
+    <span class="kd">public</span> <span class="k">var</span> <span class="nv">standalone</span><span class="p">:</span> <span class="kt">Bool</span> <span class="o">=</span> <span class="kc">false</span>
+    <span class="kd">public</span> <span class="k">var</span> <span class="nv">stylesheet</span><span class="p">:</span> <span class="kt">String</span><span class="p">?</span> <span class="o">=</span> <span class="kc">nil</span>
+    <span class="kd">public</span> <span class="k">var</span> <span class="nv">title</span><span class="p">:</span> <span class="kt">String</span><span class="p">?</span> <span class="o">=</span> <span class="kc">nil</span>
+    <span class="kd">public</span> <span class="k">var</span> <span class="nv">hardBreaks</span><span class="p">:</span> <span class="kt">Bool</span> <span class="o">=</span> <span class="kc">false</span>
+    <span class="kd">public</span> <span class="k">var</span> <span class="nv">generateHeaderIDs</span><span class="p">:</span> <span class="kt">Bool</span> <span class="o">=</span> <span class="kc">false</span>
+    <span class="kd">public</span> <span class="k">var</span> <span class="nv">unsafe</span><span class="p">:</span> <span class="kt">Bool</span> <span class="o">=</span> <span class="kc">false</span>
+    <span class="kd">public</span> <span class="k">var</span> <span class="nv">headerAnchors</span><span class="p">:</span> <span class="kt">Bool</span> <span class="o">=</span> <span class="kc">false</span>
+    <span class="kd">public</span> <span class="k">var</span> <span class="nv">obfuscateEmails</span><span class="p">:</span> <span class="kt">Bool</span> <span class="o">=</span> <span class="kc">false</span>
+    <span class="kd">public</span> <span class="k">var</span> <span class="nv">embedImages</span><span class="p">:</span> <span class="kt">Bool</span> <span class="o">=</span> <span class="kc">false</span>
+    <span class="kd">public</span> <span class="kd">static</span> <span class="kd">let</span> <span class="p">`</span><span class="nv">default</span><span class="p">`</span> <span class="o">=</span> <span class="kt">ApexOptions</span><span class="p">()</span>
+<span class="p">}</span>
+</code></pre>
+<p>
+<strong>  Example usage:</strong>
+</p>
+<pre><code class="highlight language-swift"><span class="k">var</span> <span class="nv">options</span> <span class="o">=</span> <span class="kt">ApexOptions</span><span class="o">.</span><span class="k">default</span>
+<span class="n">options</span><span class="o">.</span><span class="n">pretty</span> <span class="o">=</span> <span class="kc">true</span>
+<span class="n">options</span><span class="o">.</span><span class="n">generateHeaderIDs</span> <span class="o">=</span> <span class="kc">true</span>
+<span class="k">let</span> <span class="nv">html</span> <span class="o">=</span> <span class="n">markdown</span><span class="o">.</span><span class="nf">apexHTML</span><span class="p">(</span><span class="nv">mode</span><span class="p">:</span> <span class="o">.</span><span class="n">gfm</span><span class="p">,</span> <span class="nv">options</span><span class="p">:</span> <span class="n">options</span><span class="p">)</span>
+</code></pre>
+<h3 id="objective-c-bridge-alternative">
+  Objective-C Bridge (Alternative)
+</h3>
+<p>
+  You can also use the Objective-C API directly from Swift:
+</p>
+<pre><code class="highlight language-swift"><span class="kd">import</span> <span class="kt">Foundation</span>
+ <span class="kt">Use</span> <span class="kt">Objective</span><span class="o">-</span><span class="kt">C</span> <span class="n">wrapper</span>
+<span class="k">let</span> <span class="nv">html</span> <span class="o">=</span> <span class="kt">NSString</span><span class="o">.</span><span class="nf">convert</span><span class="p">(</span><span class="nv">withApex</span><span class="p">:</span> <span class="n">markdownText</span><span class="p">)</span>
+ <span class="kt">With</span> <span class="n">mode</span> <span class="n">constants</span>
+<span class="k">let</span> <span class="nv">gfmHtml</span> <span class="o">=</span> <span class="kt">NSString</span><span class="o">.</span><span class="nf">convert</span><span class="p">(</span><span class="nv">withApex</span><span class="p">:</span> <span class="n">markdownText</span><span class="p">,</span> <span class="nv">mode</span><span class="p">:</span> <span class="kt">ApexModeGFM</span><span class="p">)</span>
+ <span class="kt">Dictionary</span><span class="o">-</span><span class="n">based</span> <span class="n">options</span>
+<span class="k">let</span> <span class="nv">options</span><span class="p">:</span> <span class="p">[</span><span class="kt">String</span><span class="p">:</span> <span class="kt">Any</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span>
+    <span class="s">"pretty"</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
+    <span class="s">"standalone"</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
+    <span class="s">"stylesheet"</span><span class="p">:</span> <span class="s">"style.css"</span>
+<span class="p">]</span>
+<span class="k">let</span> <span class="nv">configuredHtml</span> <span class="o">=</span> <span class="kt">NSString</span><span class="o">.</span><span class="nf">convert</span><span class="p">(</span>
+    <span class="nv">withApex</span><span class="p">:</span> <span class="n">markdownText</span><span class="p">,</span>
+    <span class="nv">mode</span><span class="p">:</span> <span class="kt">ApexModeUnified</span><span class="p">,</span>
+    <span class="nv">options</span><span class="p">:</span> <span class="n">options</span>
+<span class="p">)</span>
+</code></pre>
+<p>
+  For direct C API access, create a Swift bridging header:
+</p>
+<pre><code class="highlight language-swift"> <span class="kt">Bridging</span> <span class="n">header</span>
+<span class="cp">#import &lt;Apex/apex.h&gt;</span>
+ <span class="kt">Swift</span> <span class="n">code</span>
+<span class="kd">func</span> <span class="nf">convertMarkdown</span><span class="p">(</span><span class="n">_</span> <span class="nv">text</span><span class="p">:</span> <span class="kt">String</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kt">String</span><span class="p">?</span> <span class="p">{</span>
+    <span class="k">let</span> <span class="nv">opts</span> <span class="o">=</span> <span class="nf">apex_options_default</span><span class="p">()</span>
+    <span class="k">let</span> <span class="nv">cString</span> <span class="o">=</span> <span class="n">text</span><span class="o">.</span><span class="n">utf8CString</span>
+    <span class="k">guard</span> <span class="k">let</span> <span class="nv">html</span> <span class="o">=</span> <span class="nf">apex_markdown_to_html</span><span class="p">(</span><span class="n">cString</span><span class="p">,</span> <span class="n">text</span><span class="o">.</span><span class="n">utf8</span><span class="o">.</span><span class="n">count</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">opts</span><span class="p">)</span> <span class="k">else</span> <span class="p">{</span>
+        <span class="k">return</span> <span class="kc">nil</span>
+    <span class="p">}</span>
+    <span class="k">defer</span> <span class="p">{</span> <span class="nf">apex_free_string</span><span class="p">(</span><span class="n">html</span><span class="p">)</span> <span class="p">}</span>
+    <span class="k">return</span> <span class="kt">String</span><span class="p">(</span><span class="nv">cString</span><span class="p">:</span> <span class="n">html</span><span class="p">)</span>
+<span class="p">}</span>
+</code></pre>
+<h2 id="troubleshooting">
+  Troubleshooting
+</h2>
+<h3 id="swift-package-manager-issues">
+  Swift Package Manager Issues
+</h3>
+<p>
+<strong>  Package Resolution Fails:</strong>
+</p>
+<ul>
+  <li>
+    Ensure you have an active internet connection
+  </li>
+  <li>
+    Check that the repository URL is correct: <code>https://github.com/ApexMarkdown/apex</code>
+  </li>
+  <li>
+    Try cleaning derived data: <code>File &gt; Packages &gt; Reset Package Caches</code>
+  </li>
+  <li>
+    Verify your Xcode version supports the required Swift tools version (5.7+)
+  </li>
+</ul>
+<p>
+<strong>  Build Errors:</strong>
+</p>
+<ul>
+  <li>
+    Ensure your deployment target matches Apex’s requirements (macOS 10.13+, iOS 11+)
+  </li>
+  <li>
+    Clean build folder: <code>Product &gt; Clean Build Folder</code> (Shift+Cmd+K)
+  </li>
+  <li>
+    Try removing and re-adding the package dependency
+  </li>
+</ul>
+<p>
+<strong>  Module Not Found:</strong>
+</p>
+<ul>
+  <li>
+    Ensure you’ve imported the module: <code>import Apex</code>
+  </li>
+  <li>
+    Check that the Apex library product is added to your target’s dependencies
+  </li>
+  <li>
+    Verify the package resolved successfully in the Package Dependencies tab
+  </li>
+</ul>
+<h3 id="framework-not-found">
+  Framework Not Found
+</h3>
+<p>
+  Ensure the framework is:
+</p>
+<ol>
+  <li>
+    Added to “Frameworks, Libraries, and Embedded Content”
+  </li>
+  <li>
+    Set to “Embed &amp; Sign”
+  </li>
+  <li>
+    Framework search paths are correct
+  </li>
+</ol>
+<h3 id="linker-errors">
+  Linker Errors
+</h3>
+<ul>
+  <li>
+    Ensure <code>Apex.framework</code> is linked (or Apex package is added via SPM)
+  </li>
+  <li>
+    Check framework search paths
+  </li>
+  <li>
+    Verify architecture matches (arm64 vs x86_64)
+  </li>
+</ul>
+<h3 id="runtime-errors">
+  Runtime Errors
+</h3>
+<ul>
+  <li>
+    Ensure framework is embedded (not just linked) if using framework method
+  </li>
+  <li>
+    Check code signing settings
+  </li>
+  <li>
+    Verify framework is built for correct deployment target
+  </li>
+  <li>
+    For SPM: Ensure the package is properly resolved and built
+  </li>
+</ul>
+<h2 id="performance">
+  Performance
+</h2>
+<p>
+  Apex is built on cmark-gfm, which is highly optimized:
+</p>
+<ul>
+  <li>
+    Small documents (&lt; 10KB): &lt; 10ms
+  </li>
+  <li>
+    Medium documents (&lt; 100KB): &lt; 100ms
+  </li>
+  <li>
+    Large documents (&lt; 1MB): &lt; 1s
+  </li>
+</ul>
+<p>
+  The Objective-C wrapper adds minimal overhead.
+</p>
+<h2 id="module-map">
+  Module Map
+</h2>
+<p>
+  Apex includes a module map (<code>include/apex/module.modulemap</code>) that allows Swift to import the C API directly:
+</p>
+<pre><code class="highlight language-swift"><span class="kd">import</span> <span class="kt">Apex</span>
+ <span class="kt">Direct</span> <span class="kt">C</span> <span class="kt">API</span> <span class="nf">access</span> <span class="p">(</span><span class="n">advanced</span> <span class="n">usage</span><span class="p">)</span>
+<span class="k">let</span> <span class="nv">opts</span> <span class="o">=</span> <span class="nf">apex_options_default</span><span class="p">()</span>
+ <span class="o">...</span> <span class="n">configure</span> <span class="n">options</span> <span class="o">...</span>
+<span class="k">let</span> <span class="nv">html</span> <span class="o">=</span> <span class="nf">apex_markdown_to_html</span><span class="p">(</span><span class="n">markdown</span><span class="p">,</span> <span class="n">markdown</span><span class="o">.</span><span class="n">count</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">opts</span><span class="p">)</span>
+</code></pre>
+<p>
+  The module map is automatically included when using SPM or the framework.
+</p>
+<h2 id="comparison-of-integration-methods">
+  Comparison of Integration Methods
+</h2>
+<table>
+  <thead>
+    <tr>
+      <th>
+        Method
+      </th>
+      <th>
+        Ease of Use
+      </th>
+      <th>
+        Platform Support
+      </th>
+      <th>
+        Maintenance
+      </th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+<strong>        Swift Package Manager</strong>
+      </td>
+      <td>
+        ⭐⭐⭐⭐⭐
+      </td>
+      <td>
+        macOS + iOS
+      </td>
+      <td>
+        Automatic updates
+      </td>
+    </tr>
+    <tr>
+      <td>
+        Framework
+      </td>
+      <td>
+        ⭐⭐⭐
+      </td>
+      <td>
+        macOS only
+      </td>
+      <td>
+        Manual updates
+      </td>
+    </tr>
+    <tr>
+      <td>
+        CMake
+      </td>
+      <td>
+        ⭐⭐
+      </td>
+      <td>
+        macOS + Linux
+      </td>
+      <td>
+        Manual integration
+      </td>
+    </tr>
+  </tbody>
+</table>
+<p>
+<strong>  Recommendation:</strong> Use Swift Package Manager for the easiest integration and best cross-platform support.
+</p>
+<h2 id="related">
+  Related
+</h2>
+<ul>
+  <li>
+<a href="C-API.html">    C API</a> - Direct C API documentation
+  </li>
+  <li>
+<a href="Usage.html">    Usage</a> - Basic usage examples
+  </li>
+  <li>
+<a href="Modes.html">    Modes</a> - Processor mode details
+  </li>
+</ul>
+<script>
+// Hamburger menu functionality
+(function() {
+  function initHamburgerMenu() {
+    var hamburger = document.getElementById('hamburger-menu');
+    var sidebar = document.querySelector('.main-toc, .sidebar');
+    var overlay = document.getElementById('mobile-menu-overlay');
+    if (!hamburger || !sidebar) return;
+    function toggleMenu() {
+      var isOpen = sidebar.classList.contains('mobile-open');
+      if (isOpen) {
+        sidebar.classList.remove('mobile-open');
+        hamburger.classList.remove('active');
+        if (overlay) overlay.classList.remove('active');
+      } else {
+        sidebar.classList.add('mobile-open');
+        hamburger.classList.add('active');
+        if (overlay) overlay.classList.add('active');
+      }
+    }
+    hamburger.addEventListener('click', function(e) {
+      e.stopPropagation();
+      toggleMenu();
+    });
+    if (overlay) {
+      overlay.addEventListener('click', function() {
+        toggleMenu();
+      });
+    }
+    // Close menu when clicking on a sidebar link (mobile only)
+    if (window.innerWidth <= 768) {
+      var sidebarLinks = sidebar.querySelectorAll('a');
+      sidebarLinks.forEach(function(link) {
+        link.addEventListener('click', function() {
+          setTimeout(function() {
+            sidebar.classList.remove('mobile-open');
+            hamburger.classList.remove('active');
+            if (overlay) overlay.classList.remove('active');
+          }, 100);
+        });
+      });
+    }
+    // Close menu on window resize if going to desktop
+    window.addEventListener('resize', function() {
+      if (window.innerWidth > 768) {
+        sidebar.classList.remove('mobile-open');
+        hamburger.classList.remove('active');
+        if (overlay) overlay.classList.remove('active');
+      }
+    });
+  }
+  // Initialize when DOM is ready
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', initHamburgerMenu);
+  } else {
+    initHamburgerMenu();
+  }
+})();
+</script>
+<script>
+  (function() {
+    // Clone the page TOC for floating TOC
+    function initFloatingTOC() {
+      var pageTOC = document.getElementById('page-toc-top');
+      var floatingTOCContent = document.getElementById('floating-toc-content');
+      var floatingTOC = document.getElementById('floating-toc');
+      if (!pageTOC || !floatingTOCContent || !floatingTOC) return;
+      // Clone the TOC structure
+      var tocClone = pageTOC.cloneNode(true);
+      tocClone.id = 'floating-toc-clone';
+      floatingTOCContent.appendChild(tocClone);
+      // Update all links to use smooth scrolling
+      var allTOCLinks = document.querySelectorAll('.page-toc a, .floating-toc-content a');
+      allTOCLinks.forEach(function(link) {
+        link.addEventListener('click', function(e) {
+          var href = this.getAttribute('href');
+          if (href && href.startsWith('#')) {
+            e.preventDefault();
+            var targetId = href.substring(1);
+            var targetElement = document.getElementById(targetId);
+            if (targetElement) {
+              var offset = 20; // Offset from top
+              // Function to calculate absolute position from document top
+              function getAbsoluteTop(element) {
+                var top = 0;
+                while (element) {
+                  top += element.offsetTop;
+                  element = element.offsetParent;
+                }
+                return top;
+              }
+              var absoluteTop = getAbsoluteTop(targetElement);
+              var scrollTop = window.pageYOffset || document.documentElement.scrollTop;
+              var offsetPosition = absoluteTop - offset;
+              // Only scroll if we're not already at the target position
+              if (Math.abs(scrollTop - offsetPosition) > 10) {
+                window.scrollTo({
+                  top: Math.max(0, offsetPosition),
+                  behavior: 'smooth'
+                });
+              }
+              // Update URL hash without triggering scroll
+              if (history.pushState) {
+                history.pushState(null, null, href);
+              }
+            }
+          }
+        });
+      });
+      // Handle scroll to show/hide floating TOC
+      var tocTop = pageTOC.getBoundingClientRect().top + window.pageYOffset;
+      var tocBottom = tocTop + pageTOC.offsetHeight;
+      function updateFloatingTOC() {
+        var scrollY = window.pageYOffset || document.documentElement.scrollTop;
+        if (scrollY > tocBottom) {
+          floatingTOC.classList.add('visible');
+        } else {
+          floatingTOC.classList.remove('visible');
+        }
+      }
+      // Throttle scroll events
+      var ticking = false;
+      window.addEventListener('scroll', function() {
+        if (!ticking) {
+          window.requestAnimationFrame(function() {
+            updateFloatingTOC();
+            ticking = false;
+          });
+          ticking = true;
+        }
+      });
+      // Initial check
+      updateFloatingTOC();
+    }
+    // Initialize when DOM is ready
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', initFloatingTOC);
+    } else {
+      initFloatingTOC();
+    }
+  })();
+</script>
+<footer class="page-footer"><p>Copyright 2025 Brett Terpstra, All Rights Reserved | MIT License</p></footer></body>
+</html>