apex-ruby 1.0.18 → 1.0.20

data/ext/apex_ext/apex_src/documentation/docsets/Apex.docset/Contents/Resources/Documents/Troubleshooting.html

@@ -5,8 +5,97 @@
 
       <meta charset="UTF-8">
       <meta name="viewport" content="width=device-width, initial-scale=1.0">
-      <meta name="generator" content="Apex 0.1.49">
+      <meta name="generator" content="Apex 1.1.12">
       <title>Document</title>
+      <style>
+        /* GitHub-style syntax highlighting for Pygments and Skylighting */
+        /* Don't apply background to wrapper when code highlighting is enabled - let default styles handle it */
+        .code-highlighted .highlight, .code-highlighted .sourceCode { background: inherit; border-radius: 6px; padding: 16px; overflow-x: auto; }
+        .highlight pre, .sourceCode pre { margin: 0; padding: 0; background: transparent; }
+        .highlight code, .sourceCode code { font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace; font-size: 12px; line-height: 1.45; }
+        /* Pygments classes */
+        .highlight .k { color: #d73a49; font-weight: 600; } /* Keyword */
+        .highlight .kt { color: #d73a49; } /* Keyword.Type */
+        .highlight .kd { color: #d73a49; font-weight: 600; } /* Keyword.Declaration */
+        .highlight .kn { color: #d73a49; } /* Keyword.Namespace */
+        .highlight .kp { color: #d73a49; } /* Keyword.Pseudo */
+        .highlight .kr { color: #d73a49; font-weight: 600; } /* Keyword.Reserved */
+        .highlight .n { color: #6f42c1; } /* Name */
+        .highlight .na { color: #6f42c1; } /* Name.Attribute */
+        .highlight .nc { color: #6f42c1; font-weight: 600; } /* Name.Class */
+        .highlight .no { color: #005cc5; } /* Name.Constant */
+        .highlight .nd { color: #6f42c1; font-weight: 600; } /* Name.Decorator */
+        .highlight .ni { color: #800080; } /* Name.Entity */
+        .highlight .ne { color: #990000; font-weight: 600; } /* Name.Exception */
+        .highlight .nf { color: #6f42c1; font-weight: 600; } /* Name.Function */
+        .highlight .nl { color: #6f42c1; } /* Name.Label */
+        .highlight .nn { color: #555; } /* Name.Namespace */
+        .highlight .nt { color: #22863a; } /* Name.Tag */
+        .highlight .nv { color: #e36209; } /* Name.Variable */
+        .highlight .s { color: #032f62; } /* String */
+        .highlight .sb { color: #032f62; } /* String.Backtick */
+        .highlight .sc { color: #032f62; } /* String.Char */
+        .highlight .sd { color: #032f62; } /* String.Doc */
+        .highlight .s2 { color: #032f62; } /* String.Double */
+        .highlight .se { color: #032f62; } /* String.Escape */
+        .highlight .sh { color: #032f62; } /* String.Heredoc */
+        .highlight .si { color: #032f62; } /* String.Interpol */
+        .highlight .sx { color: #032f62; } /* String.Other */
+        .highlight .sr { color: #032f62; } /* String.Regex */
+        .highlight .s1 { color: #032f62; } /* String.Single */
+        .highlight .ss { color: #032f62; } /* String.Symbol */
+        .highlight .c { color: #6a737d; font-style: italic; } /* Comment */
+        .highlight .c1 { color: #6a737d; font-style: italic; } /* Comment.Single */
+        .highlight .cm { color: #6a737d; font-style: italic; } /* Comment.Multiline */
+        .highlight .cp { color: #6a737d; font-weight: 600; } /* Comment.Preproc */
+        .highlight .cs { color: #6a737d; font-weight: 600; font-style: italic; } /* Comment.Special */
+        .highlight .m { color: #005cc5; } /* Literal.Number */
+        .highlight .mb { color: #005cc5; } /* Literal.Number.Bin */
+        .highlight .mf { color: #005cc5; } /* Literal.Number.Float */
+        .highlight .mh { color: #005cc5; } /* Literal.Number.Hex */
+        .highlight .mi { color: #005cc5; } /* Literal.Number.Integer */
+        .highlight .il { color: #005cc5; } /* Literal.Number.Integer.Long */
+        .highlight .mo { color: #005cc5; } /* Literal.Number.Oct */
+        .highlight .o { color: #d73a49; } /* Operator */
+        .highlight .ow { color: #d73a49; } /* Operator.Word */
+        .highlight .p { color: #24292e; } /* Punctuation */
+        .highlight .w { color: #e1e4e8; } /* Text.Whitespace */
+        /* Skylighting classes */
+        .sourceCode .kw { color: #d73a49; font-weight: 600; } /* Keyword */
+        .sourceCode .dt { color: #6f42c1; } /* DataType */
+        .sourceCode .dv { color: #005cc5; } /* DecVal */
+        .sourceCode .bn { color: #005cc5; } /* BaseN */
+        .sourceCode .fl { color: #005cc5; } /* Float */
+        .sourceCode .ch { color: #032f62; } /* Char */
+        .sourceCode .st { color: #032f62; } /* String */
+        .sourceCode .co { color: #6a737d; font-style: italic; } /* Comment */
+        .sourceCode .ot { color: #22863a; } /* Other */
+        .sourceCode .al { color: #e36209; font-weight: 600; } /* Alert */
+        .sourceCode .fu { color: #6f42c1; font-weight: 600; } /* Function */
+        .sourceCode .re { color: #032f62; } /* RegionMarker */
+        .sourceCode .er { color: #d73a49; font-weight: 600; } /* Error */
+        .sourceCode .cf { color: #d73a49; font-weight: 600; } /* ControlFlow */
+        .sourceCode .op { color: #d73a49; } /* Operator */
+        .sourceCode .pp { color: #6a737d; } /* Preprocessor */
+        .sourceCode .at { color: #005cc5; } /* Attribute */
+        .sourceCode .do { color: #6a737d; font-style: italic; } /* Documentation */
+        .sourceCode .an { color: #6a737d; font-weight: 600; } /* Annotation */
+        .sourceCode .cv { color: #6a737d; font-weight: 600; font-style: italic; } /* CommentVar */
+        .sourceCode .in { color: #6a737d; } /* Information */
+        .sourceCode .wa { color: #e36209; font-weight: 600; } /* Warning */
+        .sourceCode .im { color: #d73a49; } /* Import */
+        .sourceCode .bu { color: #005cc5; } /* BuiltIn */
+        .sourceCode .ex { color: #6f42c1; } /* Extension */
+        .sourceCode .va { color: #e36209; } /* Variable */
+        .sourceCode .ss { color: #032f62; } /* SpecialString */
+        .sourceCode .sc { color: #032f62; } /* SpecialChar */
+        .sourceCode .vs { color: #032f62; } /* VerbatimString */
+        .sourceCode .il { color: #005cc5; } /* Special */
+        /* Line numbers (Skylighting) */
+        .sourceCode.numberSource .sourceCode { counter-reset: line; }
+        .sourceCode.numberSource .sourceCode > span { position: relative; left: -4em; counter-increment: line; }
+        .sourceCode.numberSource .sourceCode > span > a:first-child::before { content: counter(line); position: relative; left: -1em; text-align: right; vertical-align: baseline; border: none; display: inline-block; min-width: 1em; padding-right: 0.5em; color: #aaa; }
+      </style>
       <style>
         body {
           font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
@@ -35,10 +124,52 @@
         ins { background: #d4fcbc; text-decoration: none; }
         del { background: #fbb6c2; text-decoration: line-through; }
         mark { background: #fff3cd; }
+        .smallcaps { font-variant: small-caps; }
+        .underline { text-decoration: underline; }
+        span.mark { background: #fff3cd; }
+        .hidden { display: none; }
+        .quarto-xref { font-variant: normal; }
         .critic.comment { background: #e7e7e7; color: #666; font-style: italic; }
+        .mkhashtag { color: #666; }
+        .mkstyledtag {
+          display: inline-block;
+          background: #e0e0e0;
+          padding: 3px 9px;
+          border-radius: 20px;
+          font-size: 0.9em;
+          line-height: 1.4;
+          color: #333;
+          margin: 0 2px;
+        }
       </style>
+        <meta name="paginate" content="symbols"/>
+      <meta name="highlight-language-only" content="true"/>
+      <meta name="code-line-numbers" content="false"/>
+      <meta name="code-highlight" content="pygments"/>
+      <meta name="sup-sub" content="true"/>
+      <meta name="relaxed-tables" content="true"/>
+      <meta name="includes" content="true"/>
+      <meta name="autolink" content="true"/>
+      <meta name="pretty" content="false"/>
+      <meta name="standalone" content="false"/>
+      <meta name="mode" content="unified"/>
+      <meta name="markdown-in-html" content="true"/>
+      <meta name="image-captions" content="true"/>
+      <meta name="wikilink-extension" content="html"/>
+      <meta name="wikilink-space" content="hyphen"/>
+      <meta name="wikilinks" content="true"/>
+      <meta name="widont" content="true"/>
+      <meta name="plugins" content="true"/>
+      <meta name="id-format" content="gfm"/>
+
   <style>
-/* Base styles */
+:root {
+  /* border-box width of the fixed sidebar; body offset includes a small gap */
+  --sidebar-width: 250px;
+  --sidebar-offset: 270px;
+}
+
+/* Base styles — override Apex standalone centering (max-width + margin: auto) */
 body {
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
@@ -48,6 +179,11 @@ body {
   line-height: 1.65;
   color: #1e293b;
   background-color: #fff;
+  max-width: none;
+  width: auto;
+  margin: 2rem 2rem 2rem var(--sidebar-offset);
+  padding: 0 1rem;
+  box-sizing: border-box;
 }
 
 /* Sidebar / Main TOC - wider on larger screens */
@@ -56,9 +192,10 @@ body {
   position: fixed;
   left: 0;
   top: 0;
-  width: auto;
-  min-width: 180px;
-  max-width: 250px;
+  box-sizing: border-box;
+  width: var(--sidebar-width);
+  min-width: var(--sidebar-width);
+  max-width: var(--sidebar-width);
   height: 100vh;
   overflow-y: auto;
   background: #1e293b;
@@ -67,7 +204,6 @@ body {
   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;
 }
@@ -116,11 +252,6 @@ body {
   font-weight: 500;
 }
 
-/* Body margin for sidebar */
-body {
-  margin-left: 270px;
-}
-
 /* Hamburger menu button */
 .hamburger-menu {
   display: none;
@@ -136,6 +267,7 @@ body {
   color: rgba(255, 255, 255, 0.9);
   font-size: 20px;
   line-height: 1;
+  box-sizing: border-box;
   width: 44px;
   height: 44px;
   align-items: center;
@@ -153,9 +285,7 @@ body {
 
 /* 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) */
+  left: calc(var(--sidebar-width) + 12px);
 }
 
 .hamburger-menu.active {
@@ -251,7 +381,7 @@ body {
 .floating-toc {
   position: fixed;
   top: 0;
-  left: 270px;
+  left: var(--sidebar-offset);
   right: 0;
   z-index: 50;
   opacity: 0;
@@ -677,7 +807,7 @@ ol ul {
   }
 
   body {
-    margin-left: 0;
+    margin: 2rem 1rem;
   }
 
   .floating-toc {
@@ -687,7 +817,7 @@ ol ul {
 
 </style></head>
 
-  <body>
+  <body class="code-highlighted">
 <div class="floating-toc" id="floating-toc">
   <div class="floating-toc-container">
     <div class="floating-toc-header">
@@ -702,31 +832,31 @@ ol ul {
 <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>
+<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="Callouts.html">Callouts</a></li><li><a href="Tables.html">Tables</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="Quarto-Mode.html">Quarto Mode</a></li><li><a href="Command-Line-Options.html">Command Line Options</a></li><li><a href="Rendering-Markdown-In-Terminal.html">Rendering Markdown in the Terminal</a></li><li><a href="Generating-Man-Pages.html">Generating Man Pages</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="Indices.html">Indices</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="Using-Apex-with-Jekyll.html">Using Apex with Jekyll</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="Writing-Tests.html">Writing Tests</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="Filters.html">Filters</a></li><li><a href="Troubleshooting.html">Troubleshooting</a></li><li><a href="Credits.html">Credits</a></li></ul></nav>
 
     <h1 id="troubleshooting">
       Troubleshooting
     </h1>
-<nav class="page-toc" id="page-toc-top"><ul><li><a href="#troubleshooting">Troubleshooting</a><ul><li><a href="#build-issues">Build Issues</a><ul><li><a href="#cmake-not-found">CMake Not Found</a></li><li><a href="#compilation-errors">Compilation Errors</a></li><li><a href="#linking-errors">Linking Errors</a></li></ul></li><li><a href="#runtime-issues">Runtime Issues</a><ul><li><a href="#table-not-rendering">Table Not Rendering</a></li><li><a href="#header-ids-not-generated">Header IDs Not Generated</a></li><li><a href="#math-not-rendering">Math Not Rendering</a></li><li><a href="#wiki-links-not-working">Wiki Links Not Working</a></li><li><a href="#file-includes-not-working">File Includes Not Working</a></li></ul></li><li><a href="#output-issues">Output Issues</a><ul><li><a href="#no-output">No Output</a></li><li><a href="#html-not-formatted">HTML Not Formatted</a></li><li><a href="#missing-styles">Missing Styles</a></li></ul></li><li><a href="#mode-specific-issues">Mode-Specific Issues</a><ul><li><a href="#feature-not-available">Feature Not Available</a></li><li><a href="#id-format-wrong">ID Format Wrong</a></li></ul></li><li><a href="#api-issues">API Issues</a><ul><li><a href="#memory-leaks">Memory Leaks</a></li><li><a href="#thread-safety">Thread Safety</a></li><li><a href="#framework-not-found-xcode">Framework Not Found (Xcode)</a></li></ul></li><li><a href="#performance-issues">Performance Issues</a><ul><li><a href="#slow-conversion">Slow Conversion</a></li><li><a href="#high-memory-usage">High Memory Usage</a></li></ul></li><li><a href="#getting-help">Getting Help</a></li><li><a href="#related">Related</a></li></ul></li></ul></nav>
+<nav class="page-toc" id="page-toc-top"><ul><li><a href="#troubleshooting">Troubleshooting</a><ul><li><a href="#build-issues">Build&nbsp;Issues</a><ul><li><a href="#cmake-not-found">CMake&nbsp;Not&nbsp;Found</a></li><li><a href="#compilation-errors">Compilation&nbsp;Errors</a></li><li><a href="#linking-errors">Linking&nbsp;Errors</a></li></ul></li><li><a href="#runtime-issues">Runtime&nbsp;Issues</a><ul><li><a href="#table-not-rendering">Table Not&nbsp;Rendering</a></li><li><a href="#header-ids-not-generated">Header IDs Not&nbsp;Generated</a></li><li><a href="#math-not-rendering">Math Not&nbsp;Rendering</a></li><li><a href="#wiki-links-not-working">Wiki Links Not&nbsp;Working</a></li><li><a href="#file-includes-not-working">File Includes Not&nbsp;Working</a></li></ul></li><li><a href="#output-issues">Output&nbsp;Issues</a><ul><li><a href="#no-output">No&nbsp;Output</a></li><li><a href="#html-not-formatted">HTML Not&nbsp;Formatted</a></li><li><a href="#missing-styles">Missing&nbsp;Styles</a></li></ul></li><li><a href="#mode-specific-issues">Mode-Specific&nbsp;Issues</a><ul><li><a href="#feature-not-available">Feature Not&nbsp;Available</a></li><li><a href="#id-format-wrong">ID Format&nbsp;Wrong</a></li></ul></li><li><a href="#api-issues">API&nbsp;Issues</a><ul><li><a href="#memory-leaks">Memory&nbsp;Leaks</a></li><li><a href="#thread-safety">Thread&nbsp;Safety</a></li><li><a href="#framework-not-found-xcode">Framework Not Found&nbsp;(Xcode)</a></li><li><a href="#terminal-images-show-as-raw-binary-or-garbage">Terminal images show as raw binary&nbsp;or&nbsp;garbage</a></li></ul></li><li><a href="#performance-issues">Performance&nbsp;Issues</a><ul><li><a href="#slow-conversion">Slow&nbsp;Conversion</a></li><li><a href="#high-memory-usage">High Memory&nbsp;Usage</a></li></ul></li><li><a href="#getting-help">Getting&nbsp;Help</a></li><li><a href="#related">Related</a></li></ul></li></ul></nav>
 
     <p>
       Common issues and solutions when using Apex.
     </p>
 
     <h2 id="build-issues">
-      Build Issues
+      Build&nbsp;Issues
     </h2>
 
     <h3 id="cmake-not-found">
-      CMake Not Found
+      CMake&nbsp;Not&nbsp;Found
     </h3>
 
     <p>
-<strong>      Error:</strong> <code>cmake: command not found</code>
+      <strong>Error:</strong> <code>cmake: command not found</code>
     </p>
 
     <p>
-<strong>      Solution:</strong>
+      <strong>Solution:</strong>
     </p>
 
     <ul>
@@ -746,15 +876,15 @@ ol ul {
     </ul>
 
     <h3 id="compilation-errors">
-      Compilation Errors
+      Compilation&nbsp;Errors
     </h3>
 
     <p>
-<strong>      Error:</strong> Compiler not found or incompatible
+      <strong>Error:</strong> Compiler not found or incompatible
     </p>
 
     <p>
-<strong>      Solution:</strong>
+      <strong>Solution:</strong>
     </p>
 
     <ul>
@@ -770,15 +900,15 @@ ol ul {
     </ul>
 
     <h3 id="linking-errors">
-      Linking Errors
+      Linking&nbsp;Errors
     </h3>
 
     <p>
-<strong>      Error:</strong> <code>undefined reference to apex_*</code>
+      <strong>Error:</strong> <code>undefined reference to apex_*</code>
     </p>
 
     <p>
-<strong>      Solution:</strong>
+      <strong>Solution:</strong>
     </p>
 
     <ul>
@@ -798,19 +928,19 @@ ol ul {
     </ul>
 
     <h2 id="runtime-issues">
-      Runtime Issues
+      Runtime&nbsp;Issues
     </h2>
 
     <h3 id="table-not-rendering">
-      Table Not Rendering
+      Table Not&nbsp;Rendering
     </h3>
 
     <p>
-<strong>      Problem:</strong> Tables appear as code or plain text
+      <strong>Problem:</strong> Tables appear as code or plain text
     </p>
 
     <p>
-<strong>      Solutions:</strong>
+      <strong>Solutions:</strong>
     </p>
 
     <ul>
@@ -830,15 +960,15 @@ ol ul {
     </ul>
 
     <h3 id="header-ids-not-generated">
-      Header IDs Not Generated
+      Header IDs Not&nbsp;Generated
     </h3>
 
     <p>
-<strong>      Problem:</strong> Headers don’t have <code>id</code> attributes
+      <strong>Problem:</strong> Headers don’t have <code>id</code> attributes
     </p>
 
     <p>
-<strong>      Solutions:</strong>
+      <strong>Solutions:</strong>
     </p>
 
     <ul>
@@ -858,15 +988,15 @@ ol ul {
     </ul>
 
     <h3 id="math-not-rendering">
-      Math Not Rendering
+      Math Not&nbsp;Rendering
     </h3>
 
     <p>
-<strong>      Problem:</strong> Math appears as plain text
+      <strong>Problem:</strong> Math appears as plain text
     </p>
 
     <p>
-<strong>      Solutions:</strong>
+      <strong>Solutions:</strong>
     </p>
 
     <ul>
@@ -886,15 +1016,15 @@ ol ul {
     </ul>
 
     <h3 id="wiki-links-not-working">
-      Wiki Links Not Working
+      Wiki Links Not&nbsp;Working
     </h3>
 
     <p>
-<strong>      Problem:</strong> Wiki links appear as plain text
+      <strong>Problem:</strong> Wiki links appear as plain text
     </p>
 
     <p>
-<strong>      Solutions:</strong>
+      <strong>Solutions:</strong>
     </p>
 
     <ul>
@@ -914,15 +1044,15 @@ ol ul {
     </ul>
 
     <h3 id="file-includes-not-working">
-      File Includes Not Working
+      File Includes Not&nbsp;Working
     </h3>
 
     <p>
-<strong>      Problem:</strong> Include syntax not processed
+      <strong>Problem:</strong> Include syntax not processed
     </p>
 
     <p>
-<strong>      Solutions:</strong>
+      <strong>Solutions:</strong>
     </p>
 
     <ul>
@@ -936,25 +1066,25 @@ ol ul {
       </li>
 
       <li>
-        Verify syntax: `` or <code>{{file.md}}</code>
+        Verify syntax: <code>&lt;&lt;[file.md]</code> or <code>{{file.md}}</code>
       </li>
 
     </ul>
 
     <h2 id="output-issues">
-      Output Issues
+      Output&nbsp;Issues
     </h2>
 
     <h3 id="no-output">
-      No Output
+      No&nbsp;Output
     </h3>
 
     <p>
-<strong>      Problem:</strong> Command produces no output
+      <strong>Problem:</strong> Command produces no output
     </p>
 
     <p>
-<strong>      Solutions:</strong>
+      <strong>Solutions:</strong>
     </p>
 
     <ul>
@@ -974,15 +1104,15 @@ ol ul {
     </ul>
 
     <h3 id="html-not-formatted">
-      HTML Not Formatted
+      HTML Not&nbsp;Formatted
     </h3>
 
     <p>
-<strong>      Problem:</strong> HTML is all on one line
+      <strong>Problem:</strong> HTML is all on one line
     </p>
 
     <p>
-<strong>      Solutions:</strong>
+      <strong>Solutions:</strong>
     </p>
 
     <ul>
@@ -998,15 +1128,15 @@ ol ul {
     </ul>
 
     <h3 id="missing-styles">
-      Missing Styles
+      Missing&nbsp;Styles
     </h3>
 
     <p>
-<strong>      Problem:</strong> Standalone document has no styling
+      <strong>Problem:</strong> Standalone document has no styling
     </p>
 
     <p>
-<strong>      Solutions:</strong>
+      <strong>Solutions:</strong>
     </p>
 
     <ul>
@@ -1026,19 +1156,19 @@ ol ul {
     </ul>
 
     <h2 id="mode-specific-issues">
-      Mode-Specific Issues
+      Mode-Specific&nbsp;Issues
     </h2>
 
     <h3 id="feature-not-available">
-      Feature Not Available
+      Feature Not&nbsp;Available
     </h3>
 
     <p>
-<strong>      Problem:</strong> Syntax feature doesn’t work
+      <strong>Problem:</strong> Syntax feature doesn’t work
     </p>
 
     <p>
-<strong>      Solutions:</strong>
+      <strong>Solutions:</strong>
     </p>
 
     <ul>
@@ -1058,15 +1188,15 @@ ol ul {
     </ul>
 
     <h3 id="id-format-wrong">
-      ID Format Wrong
+      ID Format&nbsp;Wrong
     </h3>
 
     <p>
-<strong>      Problem:</strong> Header IDs don’t match expected format
+      <strong>Problem:</strong> Header IDs don’t match expected format
     </p>
 
     <p>
-<strong>      Solutions:</strong>
+      <strong>Solutions:</strong>
     </p>
 
     <ul>
@@ -1086,19 +1216,19 @@ ol ul {
     </ul>
 
     <h2 id="api-issues">
-      API Issues
+      API&nbsp;Issues
     </h2>
 
     <h3 id="memory-leaks">
-      Memory Leaks
+      Memory&nbsp;Leaks
     </h3>
 
     <p>
-<strong>      Problem:</strong> Application memory usage grows
+      <strong>Problem:</strong> Application memory usage grows
     </p>
 
     <p>
-<strong>      Solutions:</strong>
+      <strong>Solutions:</strong>
     </p>
 
     <ul>
@@ -1118,15 +1248,15 @@ ol ul {
     </ul>
 
     <h3 id="thread-safety">
-      Thread Safety
+      Thread&nbsp;Safety
     </h3>
 
     <p>
-<strong>      Problem:</strong> Crashes or incorrect output in multi-threaded code
+      <strong>Problem:</strong> Crashes or incorrect output in multi-threaded code
     </p>
 
     <p>
-<strong>      Solutions:</strong>
+      <strong>Solutions:</strong>
     </p>
 
     <ul>
@@ -1146,15 +1276,15 @@ ol ul {
     </ul>
 
     <h3 id="framework-not-found-xcode">
-      Framework Not Found (Xcode)
+      Framework Not Found&nbsp;(Xcode)
     </h3>
 
     <p>
-<strong>      Problem:</strong> <code>Apex.framework</code> not found at runtime
+      <strong>Problem:</strong> <code>Apex.framework</code> not found at runtime
     </p>
 
     <p>
-<strong>      Solutions:</strong>
+      <strong>Solutions:</strong>
     </p>
 
     <ul>
@@ -1173,119 +1303,164 @@ ol ul {
 
     </ul>
 
-    <h2 id="performance-issues">
-      Performance Issues
-    </h2>
-
-    <h3 id="slow-conversion">
-      Slow Conversion
+    <h3 id="terminal-images-show-as-raw-binary-or-garbage">
+      Terminal images show as raw binary&nbsp;or&nbsp;garbage
     </h3>
 
     <p>
-<strong>      Problem:</strong> Conversion takes too long
+      <strong>Problem:</strong> <code>-t terminal</code> / <code>-t terminal256</code> prints unreadable escape sequences or binary-looking data for <code>![alt](image.png)</code> images.
     </p>
 
     <p>
-<strong>      Solutions:</strong>
+      <strong>Common causes:</strong>
     </p>
 
     <ul>
 
       <li>
-        Disable unused features: Turn off extensions you don’t need
+        <strong>Pager incompatibility:</strong> <code>less -R</code> (and most pagers) only support ANSI <strong>color</strong>, not iTerm inline-image (<code>]1337;…</code>) or Kitty graphics protocols. If <code>paginate: true</code> or <code>-p</code> is set, Apex may still embed full graphics in the buffer; use <strong><code>--paginate-symbols</code></strong> or <strong><code>paginate: symbols</code></strong> for pager-friendly chafa ANSI art, or <strong><code>--no-paginate</code></strong> for direct TTY output.
       </li>
 
       <li>
-        Check input size: Large documents take longer
+        <strong>Wrong viewer on PATH:</strong> <strong>imgcat</strong> is only used in iTerm2. In other terminals Apex prefers <strong>chafa</strong>. Install chafa: <code>brew install chafa</code>.
       </li>
 
       <li>
-        Profile: Use profiling tools to identify bottlenecks
+        <strong>Not a TTY:</strong> Inline images require stdout to be a terminal during rendering. Piping to a file shows link-style fallback.
       </li>
 
     </ul>
 
     <p>
-      You can also enable Apex’s built-in profiling output with environment variables: setting <code>APEX_PROFILE=1</code> (or <code>yes</code>/<code>true</code>) will print per-phase timings from the core converter (e.g. metadata, citations, autolinks) to stderr, while <code>APEX_PROFILE_PLUGINS=1</code> enables detailed timing for plugin execution, including a total time for each plugin phase (<code>pre_parse</code> and <code>post_render</code>) and individual timings for every discovered plugin; this is especially useful for tracking down slow external handlers or regex plugins—run commands like <code>APEX_PROFILE_PLUGINS=1 apex --plugins input.md &gt; /dev/null</code> to capture just the timing lines.
+      <strong>Debug:</strong>
     </p>
 
-    <h3 id="high-memory-usage">
-      High Memory Usage
-    </h3>
+    <div class="highlight">
+<pre><span></span><span class="nv">APEX_DEBUG_TERMINAL</span><span class="o">=</span><span class="m">1</span><span class="w"> </span>apex<span class="w"> </span>doc.md<span class="w"> </span>-t<span class="w"> </span>terminal256<span class="w"> </span>--paginate-symbols
+    </pre>
+  </div>
 
-    <p>
-<strong>      Problem:</strong> Application uses too much memory
-    </p>
+  <p>
+    Check stderr for the selected viewer, command line, and pagination mode.
+  </p>
 
-    <p>
-<strong>      Solutions:</strong>
-    </p>
+  <p>
+    See <a href="Rendering-Markdown-In-Terminal.html">Rendering Markdown in the Terminal</a>.
+  </p>
 
-    <ul>
+  <h2 id="performance-issues">
+    Performance&nbsp;Issues
+  </h2>
 
-      <li>
-        Free strings promptly: Don’t keep HTML strings longer than needed
-      </li>
+  <h3 id="slow-conversion">
+    Slow&nbsp;Conversion
+  </h3>
 
-      <li>
-        Process in chunks: For very large documents, consider splitting
-      </li>
+  <p>
+    <strong>Problem:</strong> Conversion takes too long
+  </p>
 
-      <li>
-        Check for leaks: Use memory profiling tools
-      </li>
+  <p>
+    <strong>Solutions:</strong>
+  </p>
 
-    </ul>
+  <ul>
 
-    <h2 id="getting-help">
-      Getting Help
-    </h2>
+    <li>
+      Disable unused features: Turn off extensions you don’t need
+    </li>
 
-    <p>
-      If you encounter issues not covered here:
-    </p>
+    <li>
+      Check input size: Large documents take longer
+    </li>
 
-    <ol>
+    <li>
+      Profile: Use profiling tools to identify bottlenecks
+    </li>
 
-      <li>
-        Check the <a href="Syntax.html">Syntax</a> page for correct syntax
-      </li>
+  </ul>
 
-      <li>
-        Review <a href="Modes.html">Modes</a> to ensure feature is available
-      </li>
+  <p>
+    You can also enable Apex’s built-in profiling output with environment variables: setting <code>APEX_PROFILE=1</code> (or <code>yes</code>/<code>true</code>) will print per-phase timings from the core converter (e.g. metadata, citations, autolinks) to stderr, while <code>APEX_PROFILE_PLUGINS=1</code> enables detailed timing for plugin execution, including a total time for each plugin phase (<code>pre_parse</code> and <code>post_render</code>) and individual timings for every discovered plugin; this is especially useful for tracking down slow external handlers or regex plugins—run commands like <code>APEX_PROFILE_PLUGINS=1 apex --plugins input.md &gt; /dev/null</code> to capture just the timing lines.
+  </p>
 
-      <li>
-        See <a href="Command-Line-Options.html">Command Line Options</a> for flag usage
-      </li>
+  <h3 id="high-memory-usage">
+    High Memory&nbsp;Usage
+  </h3>
 
-      <li>
-        Check <a href="C-API.html">C API</a> for programmatic issues
-      </li>
+  <p>
+    <strong>Problem:</strong> Application uses too much memory
+  </p>
 
-    </ol>
+  <p>
+    <strong>Solutions:</strong>
+  </p>
 
-    <h2 id="related">
-      Related
-    </h2>
+  <ul>
 
-    <ul>
+    <li>
+      Free strings promptly: Don’t keep HTML strings longer than needed
+    </li>
 
-      <li>
-<a href="Installation.html">        Installation</a> - Build and installation issues
-      </li>
+    <li>
+      Process in chunks: For very large documents, consider splitting
+    </li>
 
-      <li>
-<a href="Usage.html">        Usage</a> - Usage examples
-      </li>
+    <li>
+      Check for leaks: Use memory profiling tools
+    </li>
 
-      <li>
-<a href="C-API.html">        C API</a> - API-specific troubleshooting
-      </li>
+  </ul>
 
-    </ul>
+  <h2 id="getting-help">
+    Getting&nbsp;Help
+  </h2>
+
+  <p>
+    If you encounter issues not covered here:
+  </p>
+
+  <ol>
+
+    <li>
+      Check the <a href="Syntax.html">Syntax</a> page for correct syntax
+    </li>
+
+    <li>
+      Review <a href="Modes.html">Modes</a> to ensure feature is available
+    </li>
+
+    <li>
+      See <a href="Command-Line-Options.html">Command Line Options</a> for flag usage
+    </li>
+
+    <li>
+      Check <a href="C-API.html">C API</a> for programmatic issues
+    </li>
+
+  </ol>
 
-  <script>
+  <h2 id="related">
+    Related
+  </h2>
+
+  <ul>
+
+    <li>
+      <a href="Installation.html">Installation</a> - Build and installation issues
+    </li>
+
+    <li>
+      <a href="Usage.html">Usage</a> - Usage examples
+    </li>
+
+    <li>
+      <a href="C-API.html">C API</a> - API-specific troubleshooting
+    </li>
+
+  </ul>
+
+<script>
 // Hamburger menu functionality
 (function() {
   function initHamburgerMenu() {