fix(markdown): keep admonitions and definition lists inside their list

Author: auscaster

src/cli.ts

@@ -24,6 +24,7 @@ program
   .option('-H, --html-anchors', 'add HTML anchors to internal links', false)
   .option('-l, --language <lang>', 'programming language', 'cpp')
   .option('-F, --flavour <name>', 'markdown dialect for admonitions: pandoc or github', 'pandoc')
+  .option('--flavor <name>', 'alias for --flavour')
   .option('-t, --templates <dir>', 'custom templates directory')
   .option('-s, --source-root <dir>', 'source root used to resolve file-level group membership')
   .option('-f, --frontmatter', 'prepend YAML frontmatter to output files', false)
@@ -42,7 +43,7 @@ program
         anchors: opts.anchors as boolean,
         htmlAnchors: opts.htmlAnchors as boolean,
         language: opts.language as string,
-        flavour: opts.flavour as string,
+        flavour: (opts.flavor ?? opts.flavour) as string,
         templates: opts.templates as string | undefined,
         sourceRoot: opts.sourceRoot as string | undefined,
         frontmatter: opts.frontmatter as boolean,

src/parser.ts

@@ -52,18 +52,19 @@ const ADMONITIONS: Record<string, { container: string; alert: string }> = {
  * default; GitHub renders those as literal text and wants blockquote alerts,
  * where every line of the body carries the quote marker.
  */
-function renderAdmonition(kind: string, body: string, flavour: string): string {
+function renderAdmonition(kind: string, body: string, flavour: string, indent: string): string {
   const admonition = ADMONITIONS[kind];
   const prefixed = kind === 'deprecated' ? `**Deprecated.** ${body}` : body;
 
-  if (flavour !== 'github') {
-    return `\n:::${admonition.container}\n${prefixed}\n:::\n\n`;
-  }
+  const lines = flavour === 'github'
+    ? [`> [!${admonition.alert}]`, ...prefixed.trim().split('\n').map((line) => (line.trim() ? `> ${line}` : '>'))]
+    : [`:::${admonition.container}`, ...prefixed.split('\n'), ':::'];
 
-  const quoted = prefixed.trim().split('\n')
-    .map((line) => (line.trim() ? `> ${line}` : '>'))
-    .join('\n');
-  return `\n> [!${admonition.alert}]\n${quoted}\n\n`;
+  // Inside a list item the whole block has to sit at the item's content
+  // column, or it ends the list instead of belonging to it, and it closes on a
+  // single newline so the next item follows on.
+  const block = lines.map((line) => (line ? indent + line : line)).join('\n');
+  return `\n${block}\n${indent ? '' : '\n'}`;
 }
 
 function listMarker(name: string | undefined): string {
@@ -74,6 +75,13 @@ function enclosingLists(context: XmlElement[]): XmlElement[] {
   return context.filter((el) => LIST_ELEMENTS.has(el['#name'] ?? ''));
 }
 
+/** Column at which the content of the current list item continues. */
+function listContentIndent(context: XmlElement[]): string {
+  return enclosingLists(context)
+    .map((el) => ' '.repeat(listMarker(el['#name']).length))
+    .join('');
+}
+
 /**
  * Indent for a list item, which Markdown measures against the marker of the
  * item it nests under, so an ordered parent indents further than a bullet.
@@ -178,7 +186,9 @@ function toMarkdown(element: unknown, context: XmlElement[] = [], options: Markd
       context.push(el);
       break;
     case 'varlistentry':
-      s = '\n* ';
+      // The entry before this one already ended its line, so starting with a
+      // newline here would put a blank line between every term.
+      s = listIndent(context) + '* ';
       break;
     case 'term':
       s = '**';
@@ -300,7 +310,7 @@ function toMarkdown(element: unknown, context: XmlElement[] = [], options: Markd
     case 'simplesect': {
       const closeKind = el.$?.kind;
       s = closeKind && ADMONITIONS[closeKind]
-        ? renderAdmonition(closeKind, s, parserOptions?.flavour ?? 'pandoc')
+        ? renderAdmonition(closeKind, s, parserOptions?.flavour ?? 'pandoc', listContentIndent(context))
         : `${s}\n\n`;
       context.pop();
       break;

src/templates.ts

@@ -19,7 +19,8 @@ const DEFAULT_RENDER_CONTEXT: RenderContext = {
   headingBase: 1,
 };
 
-const MARKDOWN_LINK = /\[([^\]]+)\]\(([^)]+)\)/g;
+const MARKDOWN_LINK = /\[([^\]]+)\]\(([^)]+)\)/;
+const MARKDOWN_LINKS = /\[([^\]]+)\]\(([^)]+)\)/g;
 
 /**
  * Render a type for a table cell.
@@ -34,11 +35,8 @@ function typeCell(type: string): string {
   const trimmed = (type || '').trim();
   if (!trimmed) return '';
 
-  MARKDOWN_LINK.lastIndex = 0;
   if (!MARKDOWN_LINK.test(trimmed)) return `\`${trimmed}\``;
-
-  MARKDOWN_LINK.lastIndex = 0;
-  return trimmed.replace(MARKDOWN_LINK, '[`$1`]($2)');
+  return trimmed.replace(MARKDOWN_LINKS, '[`$1`]($2)');
 }
 
 function headingLevel(relativeLevel: unknown, context: RenderContext): number {

test/fixtures/macros/src/macros.h

@@ -56,6 +56,19 @@ void flush(void);
        1. acquire
        2. verify
   2. close
+
+  Terms:
+
+  <dl>
+    <dt>pending</dt><dd>queued but not started</dd>
+    <dt>settled</dt><dd>finished either way</dd>
+  </dl>
+
+  Caveats:
+
+  - the queue may grow while draining
+    @note callers should not rely on the count
+  - draining twice is safe
 */
 void drain(void);
 

test/fixtures/macros/xml-out/xml/macros_8h.xml

@@ -91,7 +91,7 @@
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="src/macros.h" line="83" column="9" bodyfile="src/macros.h" bodystart="83" bodyend="-1"/>
+        <location file="src/macros.h" line="96" column="9" bodyfile="src/macros.h" bodystart="96" bodyend="-1"/>
       </memberdef>
     </sectiondef>
     <sectiondef kind="var">
@@ -106,7 +106,7 @@
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="src/macros.h" line="77" column="11"/>
+        <location file="src/macros.h" line="90" column="11"/>
       </memberdef>
     </sectiondef>
     <sectiondef kind="func">
@@ -187,13 +187,31 @@
 </listitem><listitem><para>verify</para>
 </listitem></orderedlist>
 </para>
-</listitem><listitem><para>close </para>
+</listitem><listitem><para>close</para>
 </listitem></orderedlist>
+</para>
+<para>Terms:</para>
+<para><variablelist>
+<varlistentry><term>pending</term></varlistentry>
+<listitem><para>queued but not started </para>
+</listitem>
+<varlistentry><term>settled</term></varlistentry>
+<listitem><para>finished either way </para>
+</listitem>
+</variablelist>
+</para>
+<para>Caveats:</para>
+<para><itemizedlist>
+<listitem><para>the queue may grow while draining <simplesect kind="note"><para>callers should not rely on the count</para>
+</simplesect>
+</para>
+</listitem><listitem><para>draining twice is safe </para>
+</listitem></itemizedlist>
 </para>
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="src/macros.h" line="60" column="6" declfile="src/macros.h" declline="60" declcolumn="6"/>
+        <location file="src/macros.h" line="73" column="6" declfile="src/macros.h" declline="73" declcolumn="6"/>
       </memberdef>
       <memberdef kind="function" id="macros_8h_1af6f5804d6181b428b0abd148e8005ff6" prot="public" static="no" const="no" explicit="no" inline="no" virt="non-virtual">
         <type>struct <ref refid="structhandlers" kindref="compound">handlers</ref> *</type>
@@ -235,7 +253,7 @@
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="src/macros.h" line="92" column="15" declfile="src/macros.h" declline="92" declcolumn="15"/>
+        <location file="src/macros.h" line="105" column="15" declfile="src/macros.h" declline="105" declcolumn="15"/>
       </memberdef>
     </sectiondef>
     <briefdescription>
@@ -258,19 +276,19 @@
 <codeline lineno="29"><highlight class="normal"></highlight></codeline>
 <codeline lineno="39" refid="macros_8h_1a0a9e9396972b76c5947592479860020d" refkind="member"><highlight class="normal"></highlight><highlight class="keywordtype">void</highlight><highlight class="normal"><sp/><ref refid="macros_8h_1a0a9e9396972b76c5947592479860020d" kindref="member">flush</ref>(</highlight><highlight class="keywordtype">void</highlight><highlight class="normal">);</highlight></codeline>
 <codeline lineno="40"><highlight class="normal"></highlight></codeline>
-<codeline lineno="60" refid="macros_8h_1a8168e46e61860b969b9ee6c101bbc1c9" refkind="member"><highlight class="normal"></highlight><highlight class="keywordtype">void</highlight><highlight class="normal"><sp/><ref refid="macros_8h_1a8168e46e61860b969b9ee6c101bbc1c9" kindref="member">drain</ref>(</highlight><highlight class="keywordtype">void</highlight><highlight class="normal">);</highlight></codeline>
-<codeline lineno="61"><highlight class="normal"></highlight></codeline>
-<codeline lineno="65" refid="structhandlers" refkind="compound"><highlight class="normal"></highlight><highlight class="keyword">struct<sp/></highlight><highlight class="normal"><ref refid="structhandlers" kindref="compound">handlers</ref><sp/>{</highlight></codeline>
-<codeline lineno="73" refid="structhandlers_1a996535b7879fb9713680e41af2b2791a" refkind="member"><highlight class="normal"><sp/><sp/>int<sp/>(*<ref refid="structhandlers_1a996535b7879fb9713680e41af2b2791a" kindref="member">retry</ref>)(</highlight><highlight class="keywordtype">int</highlight><highlight class="normal"><sp/>attempt,<sp/></highlight><highlight class="keyword">const</highlight><highlight class="normal"><sp/></highlight><highlight class="keywordtype">char</highlight><highlight class="normal"><sp/>*reason);</highlight></codeline>
+<codeline lineno="73" refid="macros_8h_1a8168e46e61860b969b9ee6c101bbc1c9" refkind="member"><highlight class="normal"></highlight><highlight class="keywordtype">void</highlight><highlight class="normal"><sp/><ref refid="macros_8h_1a8168e46e61860b969b9ee6c101bbc1c9" kindref="member">drain</ref>(</highlight><highlight class="keywordtype">void</highlight><highlight class="normal">);</highlight></codeline>
 <codeline lineno="74"><highlight class="normal"></highlight></codeline>
-<codeline lineno="76" refid="structhandlers_1adb541f4c21033e417256fd5cab26e6b2" refkind="member"><highlight class="normal"><sp/><sp/></highlight><highlight class="keyword">struct<sp/></highlight><highlight class="normal"><ref refid="structhandlers" kindref="compound">handlers</ref><sp/>*<ref refid="structhandlers_1adb541f4c21033e417256fd5cab26e6b2" kindref="member">fallback</ref>;</highlight></codeline>
-<codeline lineno="77" refid="macros_8h_1a37285142ae15ca3cdc36f3a03faeb0c9" refkind="member"><highlight class="normal">}<sp/>*<ref refid="macros_8h_1a37285142ae15ca3cdc36f3a03faeb0c9" kindref="member">registry</ref>;</highlight></codeline>
-<codeline lineno="78"><highlight class="normal"></highlight></codeline>
-<codeline lineno="83" refid="macros_8h_1a1ee636c8ea8ef76556c00290eb5a289b" refkind="member"><highlight class="normal"></highlight><highlight class="preprocessor">#define<sp/>RETRY_HOOK<sp/>registry-&gt;retry</highlight><highlight class="normal"></highlight></codeline>
-<codeline lineno="84"><highlight class="normal"></highlight></codeline>
-<codeline lineno="92" refid="macros_8h_1af6f5804d6181b428b0abd148e8005ff6" refkind="member"><highlight class="normal"></highlight><highlight class="keyword">struct<sp/></highlight><highlight class="normal"><ref refid="structhandlers" kindref="compound">handlers</ref><sp/>*<ref refid="macros_8h_1af6f5804d6181b428b0abd148e8005ff6" kindref="member">configure</ref>(</highlight><highlight class="keyword">struct</highlight><highlight class="normal"><sp/><ref refid="structhandlers" kindref="compound">handlers</ref><sp/>*target,<sp/></highlight><highlight class="keywordtype">int</highlight><highlight class="normal"><sp/>count);</highlight></codeline>
-<codeline lineno="93"><highlight class="normal"></highlight></codeline>
-<codeline lineno="94"><highlight class="normal"></highlight><highlight class="preprocessor">#endif<sp/></highlight><highlight class="comment">/*<sp/>__MACROS_H__<sp/>*/</highlight><highlight class="preprocessor"></highlight></codeline>
+<codeline lineno="78" refid="structhandlers" refkind="compound"><highlight class="normal"></highlight><highlight class="keyword">struct<sp/></highlight><highlight class="normal"><ref refid="structhandlers" kindref="compound">handlers</ref><sp/>{</highlight></codeline>
+<codeline lineno="86" refid="structhandlers_1a996535b7879fb9713680e41af2b2791a" refkind="member"><highlight class="normal"><sp/><sp/>int<sp/>(*<ref refid="structhandlers_1a996535b7879fb9713680e41af2b2791a" kindref="member">retry</ref>)(</highlight><highlight class="keywordtype">int</highlight><highlight class="normal"><sp/>attempt,<sp/></highlight><highlight class="keyword">const</highlight><highlight class="normal"><sp/></highlight><highlight class="keywordtype">char</highlight><highlight class="normal"><sp/>*reason);</highlight></codeline>
+<codeline lineno="87"><highlight class="normal"></highlight></codeline>
+<codeline lineno="89" refid="structhandlers_1adb541f4c21033e417256fd5cab26e6b2" refkind="member"><highlight class="normal"><sp/><sp/></highlight><highlight class="keyword">struct<sp/></highlight><highlight class="normal"><ref refid="structhandlers" kindref="compound">handlers</ref><sp/>*<ref refid="structhandlers_1adb541f4c21033e417256fd5cab26e6b2" kindref="member">fallback</ref>;</highlight></codeline>
+<codeline lineno="90" refid="macros_8h_1a37285142ae15ca3cdc36f3a03faeb0c9" refkind="member"><highlight class="normal">}<sp/>*<ref refid="macros_8h_1a37285142ae15ca3cdc36f3a03faeb0c9" kindref="member">registry</ref>;</highlight></codeline>
+<codeline lineno="91"><highlight class="normal"></highlight></codeline>
+<codeline lineno="96" refid="macros_8h_1a1ee636c8ea8ef76556c00290eb5a289b" refkind="member"><highlight class="normal"></highlight><highlight class="preprocessor">#define<sp/>RETRY_HOOK<sp/>registry-&gt;retry</highlight><highlight class="normal"></highlight></codeline>
+<codeline lineno="97"><highlight class="normal"></highlight></codeline>
+<codeline lineno="105" refid="macros_8h_1af6f5804d6181b428b0abd148e8005ff6" refkind="member"><highlight class="normal"></highlight><highlight class="keyword">struct<sp/></highlight><highlight class="normal"><ref refid="structhandlers" kindref="compound">handlers</ref><sp/>*<ref refid="macros_8h_1af6f5804d6181b428b0abd148e8005ff6" kindref="member">configure</ref>(</highlight><highlight class="keyword">struct</highlight><highlight class="normal"><sp/><ref refid="structhandlers" kindref="compound">handlers</ref><sp/>*target,<sp/></highlight><highlight class="keywordtype">int</highlight><highlight class="normal"><sp/>count);</highlight></codeline>
+<codeline lineno="106"><highlight class="normal"></highlight></codeline>
+<codeline lineno="107"><highlight class="normal"></highlight><highlight class="preprocessor">#endif<sp/></highlight><highlight class="comment">/*<sp/>__MACROS_H__<sp/>*/</highlight><highlight class="preprocessor"></highlight></codeline>
     </programlisting>
     <location file="src/macros.h"/>
   </compounddef>

test/fixtures/macros/xml-out/xml/structhandlers.xml

@@ -37,7 +37,7 @@
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="src/macros.h" line="73" column="3" bodyfile="src/macros.h" bodystart="73" bodyend="-1"/>
+        <location file="src/macros.h" line="86" column="3" bodyfile="src/macros.h" bodystart="86" bodyend="-1"/>
       </memberdef>
       <memberdef kind="variable" id="structhandlers_1adb541f4c21033e417256fd5cab26e6b2" prot="public" static="no" mutable="no">
         <type>struct <ref refid="structhandlers" kindref="compound">handlers</ref> *</type>
@@ -52,7 +52,7 @@
         </detaileddescription>
         <inbodydescription>
         </inbodydescription>
-        <location file="src/macros.h" line="76" column="17" bodyfile="src/macros.h" bodystart="76" bodyend="-1"/>
+        <location file="src/macros.h" line="89" column="17" bodyfile="src/macros.h" bodystart="89" bodyend="-1"/>
       </memberdef>
     </sectiondef>
     <briefdescription>
@@ -69,7 +69,7 @@
         </childnode>
       </node>
     </collaborationgraph>
-    <location file="src/macros.h" line="65" column="1" bodyfile="src/macros.h" bodystart="65" bodyend="77"/>
+    <location file="src/macros.h" line="78" column="1" bodyfile="src/macros.h" bodystart="78" bodyend="90"/>
     <listofallmembers>
       <member refid="structhandlers_1adb541f4c21033e417256fd5cab26e6b2" prot="public" virt="non-virtual"><scope>handlers</scope><name>fallback</name></member>
       <member refid="structhandlers_1a996535b7879fb9713680e41af2b2791a" prot="public" virt="non-virtual"><scope>handlers</scope><name>retry</name></member>

test/integration.test.ts

@@ -551,6 +551,9 @@ describe('integration', () => {
     expect(api).toContain('> [!IMPORTANT]\n> Never call this from a signal handler.');
     // GitHub renders the Pandoc container syntax as literal text.
     expect(api).not.toContain(':::');
+    // An alert inside a list item sits at the item's content column, or it
+    // ends the list instead of belonging to it.
+    expect(api).toContain('  > [!NOTE]\n  > callers should not rely on the count');
   });
 
   it('renders macros by their real shape and keeps undocumented ones', async () => {

test/snapshots/macros/api.md

@@ -80,7 +80,7 @@ Defined in src/macros.h:23
 #define RETRY_HOOK registry->retry
 ```
 
-Defined in src/macros.h:83
+Defined in src/macros.h:96
 
 Shorthand for the registry retry hook. Its initializer references another documented symbol, so Doxygen emits a cross-reference inside the initializer.
 
@@ -146,7 +146,7 @@ Never call this from a signal handler.
 void drain(void)
 ```
 
-Defined in src/macros.h:60
+Defined in src/macros.h:73
 
 Drain the queue.
 
@@ -166,6 +166,20 @@ Steps:
    1. verify
 1. close
 
+Terms:
+
+* **pending**: queued but not started 
+* **settled**: finished either way 
+
+Caveats:
+
+* the queue may grow while draining 
+  :::note
+  callers should not rely on the count
+
+  :::
+* draining twice is safe
+
 ---
 
 {#configure}
@@ -176,7 +190,7 @@ Steps:
 struct handlers * configure(struct handlers * target, int count)
 ```
 
-Defined in src/macros.h:92
+Defined in src/macros.h:105
 
 Configure a handler registry.
 
@@ -204,6 +218,6 @@ struct handlers * registry
 
 Type: struct [`handlers`](handlers.md#handlers) *
 
-Defined in src/macros.h:77
+Defined in src/macros.h:90
 
 Generated by [Moxygen](https://0state.com/moxygen)

test/snapshots/macros/handlers.md

@@ -10,7 +10,7 @@
 struct handlers
 ```
 
-Defined in src/macros.h:65
+Defined in src/macros.h:78
 
 Registry of handler hooks.
 
@@ -31,7 +31,7 @@ Registry of handler hooks.
 int(* retry)(int attempt, const char *reason)
 ```
 
-Defined in src/macros.h:73
+Defined in src/macros.h:86
 
 Called when a retry is scheduled.
 
@@ -57,7 +57,7 @@ struct handlers * fallback
 
 Type: struct [`handlers`](#handlers) *
 
-Defined in src/macros.h:76
+Defined in src/macros.h:89
 
 The registry consulted when this one has no handler.