Markdown collapsible section: details tags in pandoc

In these tests, a markdown collapsible section means an HTML <details> element typed into Markdown source, with a <summary> line as its first child. In these pandoc 3.8.3 runs, markdown treated text inside those tags one way, and commonmark and commonmark_x treated it another.

The commands below were run once apiece on a macOS computer, using the readers commonmark_x, commonmark and markdown. What follows is pandoc's HTML, copied from the logs. How any program might display that HTML to a person was never tested here.

Test file and reader commands

The input is details.md. Running awk 'END{print NR}' details.md printed 20, so the file has 20 lines. Here it is as cat details.md printed it:

<details>
<summary>Test log</summary>
**3 tests failed**
</details>

<details open>
<summary>Open by default</summary>

- item one

</details>

<details>
<summary>Fence inside</summary>

```bash
npm test
```

</details>

The file holds three <details> blocks. Block one has no blank line anywhere inside it. Block two carries an open attribute plus a list holding one item, and blank lines sit on both sides of that list. Block three holds a fenced bash block, also set off by blank lines.

One command per reader converted it:

pandoc -f markdown -t html details.md
pandoc -f commonmark -t html details.md
pandoc -f commonmark_x -t html details.md

Each of the three runs returned rc 0 and printed an HTML fragment.

Bold text with no blank lines around it

Block one came out of markdown like this:

<details>
<summary>
Test log
</summary>
<strong>3 tests failed</strong>
</details>

With commonmark, the block read:

<details>
<summary>Test log</summary>
**3 tests failed**
</details>

Those four lines also came from commonmark_x, byte for byte. So the markdown reader turned the double asterisks into a <strong> element, while commonmark and commonmark_x left the asterisks in place as plain characters.

The extension lists match this divide. In the list pandoc --list-extensions printed for markdown, line 42 reads +markdown_in_html_blocks. A grep -c for that name counted 1 line in the markdown list, 0 in the commonmark list and 0 in the commonmark_x list. It is a pandoc extension, and it does not appear in either CommonMark reader's list at all.

Why blank lines matter around HTML blocks is explained in raw HTML in Markdown; this page sticks with output.

Open attribute on the second block

Block two opens with <details open>. In the three runs, the output kept that tag as <details open>, attribute and all.

Pandoc's raw_html extension is switched on in the three lists: +raw_html sits at line 53 of the markdown list and at line 18 of the commonmark and commonmark_x lists. That fits the tag passing through. The test stopped at the HTML pandoc produced.

Where the summary text landed

Line breaks inside <summary> came out differently under markdown than under commonmark and commonmark_x. The markdown run moved the summary text to a separate line, sandwiched by <summary> and </summary>:

<summary>
Open by default
</summary>

Under commonmark and commonmark_x, it stayed on one line as <summary>Open by default</summary>, matching the input.

The markdown output for details.md has no empty lines, while the commonmark output and the commonmark_x output have four empty lines apiece.

List and fence set off by blank lines

Blocks two and three gave matching bodies under the three readers. The list came out as:

<ul>
<li>item one</li>
</ul>

For the fenced bash block, pandoc wrote:

<div class="sourceCode" id="cb1"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="ex">npm</span> test</span></code></pre></div>

The three readers wrote these lines identically. For these two blocks, the summary lines and the empty lines were where markdown parted ways with commonmark and commonmark_x. Fence syntax is the subject of Markdown code blocks.

Bold line padded with blank lines

An extra script retried block one after padding the bold line with one empty line above and one below. The file details-blank.md is 6 lines long by the same awk count:

<details>
<summary>Test log</summary>

**3 tests failed**

</details>

The markdown reader returned:

<details>
<summary>
Test log
</summary>
<p><strong>3 tests failed</strong></p>
</details>

From commonmark came the lines below, and commonmark_x printed them identically:

<details>
<summary>Test log</summary>

<p><strong>3 tests failed</strong></p>
</details>

Once those two blank lines were in, the three readers each wrapped the bold text in <p><strong>. The summary line still differed: split over three lines under markdown, kept whole under commonmark and commonmark_x.

Details nested inside details

The file details-nested.md has 11 lines and puts one block inside another, with blank lines between the parts:

<details>
<summary>Outer</summary>

<details>
<summary>Inner</summary>

Inner **text**

</details>

</details>

Output from markdown:

<details>
<summary>
Outer
</summary>
<details>
<summary>
Inner
</summary>
<p>Inner <strong>text</strong></p>
</details>
</details>

Pandoc wrote the following for commonmark, and the same for commonmark_x:

<details>
<summary>Outer</summary>

<details>
<summary>Inner</summary>

<p>Inner <strong>text</strong></p>
</details>

</details>

Both nesting levels survived in the three runs, and each reader turned the inner bold text into <strong>.

Code span in the summary

The 6-line file details-codespan.md puts a code span on the summary line:

<details>
<summary>Run `npm test`</summary>

Done.

</details>

Under markdown, the summary came out as Run <code>npm test</code> on its own line:

<details>
<summary>
Run <code>npm test</code>
</summary>
<p>Done.</p>
</details>

Under commonmark and commonmark_x, the backticks stayed as typed:

<details>
<summary>Run `npm test`</summary>

<p>Done.</p>
</details>

Put plainly, backticks on the summary line produced <code> under markdown, while commonmark and commonmark_x kept them as backtick text.

Details block in a list item

The file details-list.md is 8 lines and indents a block under a bullet:

- Step one

  <details>
  <summary>More</summary>

  Step **detail**

  </details>

The markdown reader printed:

<ul>
<li><p>Step one</p>
<details>
<summary>
<p>More</p>
</summary>
<p>Step <strong>detail</strong></p>
</details></li>
</ul>

From commonmark, with commonmark_x matching it line for line:

<ul>
<li><p>Step one</p>
<details>
<summary>More</summary>

<p>Step <strong>detail</strong></p>
</details>
</li>
</ul>

Under markdown, the summary text gained a <p> wrapper inside the list item. Under commonmark and commonmark_x, it did not. The bold body text became <strong> in the three runs.

Switching markdown_in_html_blocks off

A reader name can carry a minus sign followed by an extension name. The extra script applied that form to details.md:

pandoc -f markdown-markdown_in_html_blocks -t html details.md

It returned rc 0 and printed:

<details>
<summary>Test log</summary>
**3 tests failed**
</details>
<details open>
<summary>Open by default</summary>

- item one

</details>
<details>
<summary>Fence inside</summary>

```bash
npm test
```

</details>

With that extension removed, markdown kept the asterisks, the list dash and the backtick fence as plain text inside the three blocks. The summary lines stayed whole too. The empty lines between the blocks were gone, as in the default markdown run.

Counting tags with grep

The extra script issued these commands after a cd into the test folder. Replace the file name with yours to repeat them.

pandoc -f markdown -t html details.md -o details-out-markdown.html
pandoc -f commonmark -t html details.md -o details-out-commonmark.html
pandoc -f commonmark_x -t html details.md -o details-out-commonmark_x.html
grep -c '<strong>' details-out-markdown.html
grep -c '<strong>' details-out-commonmark.html
grep -c '<strong>' details-out-commonmark_x.html
grep -c '<details open>' details-out-markdown.html
grep -c '<details open>' details-out-commonmark.html
grep -c '<details open>' details-out-commonmark_x.html

1. Run the pandoc lines, which write one output file per reader. The log records rc 0 for those three runs.
2. Count <strong> lines. The counts were 1 for markdown, 0 for commonmark and 0 for commonmark_x.
3. Count <details open> lines. Every file gave 1 here.

A count of 0 in step 2 lines up with the asterisks that commonmark and commonmark_x left in block one. The sibling post on diff fences in Markdown puts the same three readers to work on a diff fence.

Where Sashmark fits

If Sashmark turns out as planned, you could fix a typo by clicking into the rendered page and typing. On save, the Round-Trip step is designed to write that single fix back and leave each neighboring byte alone. Changes View, a second planned feature, would flag sections an agent revised behind your back, whether or not the folder sits under git.

It is in development and has not been released. The app itself has no AI features. See the planned features, the help pages and the roadmap for where each part stands.

More at sashmark.com.