Markdown include file: pandoc output for three forms

The idea behind a markdown include file line is that one document carries the text of a second file at that spot. Three such forms came back out of pandoc as plain paragraphs of literal text in this test, under its commonmark_x, markdown and plain commonmark readers, and no second file's text showed up in any run.

I ran every command here one time on macOS. Its pandoc --version check printed pandoc 3.8.3. Below you get pandoc's HTML exactly as printed, and I make no guess about how other programs treat these lines. Pointing to another file with a link is a separate subject, covered in links to local files.

Three include forms in one input

The main input is include.md. It holds an intro line, three include forms and a closing line. Running cat include.md printed:

Intro for Jane Doe.

!include notes/setup.md

![[setup]]

{{< include notes/setup.md >}}

End.

Line three is a bang-include line. Line five is a double-bracket embed; for the bracket syntax on its own, see wikilinks. Line seven is a curly-brace shortcode. Blank lines sit between the forms, so each one stands apart from its neighbors in the file.

Two of the forms name notes/setup.md as their target, and the embed names setup. The test folder has no notes subfolder at all. A later section fixes that and runs the file again.

What the three readers printed

The main test script sent the file through pandoc once per reader. Here are the three commands, written as you would type them inside the test folder:

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

Output from the -f markdown run:

<p>Intro for Jane Doe.</p>
<p>!include notes/setup.md</p>
<p>![[setup]]</p>
<p>{{&lt; include notes/setup.md &gt;}}</p>
<p>End.</p>

The commonmark section and the commonmark_x section of the log hold those same five lines, and the three runs each closed with rc 0. The extra script repeated all three runs and got matching output.

Here is how each form came out, reader by reader:

• The bang-include line became <p>!include notes/setup.md</p> under markdown, under commonmark and under commonmark_x. The exclamation mark and the path both survived as text.
• The double-bracket embed became <p>![[setup]]</p> under the three readers. Pandoc built no <img> element from it in any of these runs.
• The curly-brace shortcode came through as text under the three readers as well. Its braces stayed as typed, while its two angle brackets were written out as < and >.

The intro and End. framed those three paragraphs in each run, with nothing placed between them. Across these runs, no text from another file appeared in what the commonmark_x, markdown or plain commonmark reader wrote.

A real notes file beside the input

A fair objection to that main run: the target file was missing, so there was nothing to pull in. The extra script covered that case. It set up a folder named include-dir holding a copy of include.md and a notes/setup.md file with one line in it. Running cmp on the copy and the original gave rc 0, so the two inputs have identical bytes.

The target file reads:

Setup steps for Doe Holdings.

To repeat the check yourself, run these from the test folder:

cd include-dir
ls notes
pandoc -f markdown -t html include.md -o include-out-markdown.html
grep -c 'Setup steps' include-out-markdown.html
grep -c 'include' include-out-markdown.html

1. Run ls notes first. It printed setup.md, which confirms the target sits where the input's path points.
2. Convert include.md with the markdown reader. The pandoc line exited with rc 0. My extra script printed what commonmark_x, markdown and plain commonmark wrote in that folder too, and the three outputs equal the five-line block from the previous section.
3. Count the setup text in the saved output. grep -c 'Setup steps' gave 0, so the line from notes/setup.md never reached the markdown output.
4. Run the control count on that same saved file. grep -c 'include' gave 2, one for the bang-include paragraph and one for the shortcode paragraph. A nonzero count there shows the grep was reading a real file with real text in it.

So a present target file changed nothing in this test. The three forms stayed literal under all three readers whether notes/setup.md existed or not.

Joining files with cat before rendering

If the aim is one output built from several Markdown parts, the shell can join them before pandoc ever sees them. Pandoc then reads a single input file. The two parts for this test are short.

cat include-intro.md printed:

Intro for Jane Doe.

cat include-setup.md printed:

Setup steps for Doe Holdings.

Follow these steps from the test folder:

cat include-intro.md include-setup.md > include-joined.md
cat include-joined.md
pandoc -f commonmark -t html include-joined.md

1. Join the parts with cat, which wrote the two files one after the other into include-joined.md. The command exited with rc 0.
2. Print the joined file to check it. The output was two lines with no gap:

Intro for Jane Doe.
Setup steps for Doe Holdings.

3. Render the joined file. Output under commonmark:

<p>Intro for Jane Doe. Setup steps for Doe Holdings.</p>

The markdown and commonmark_x runs on include-joined.md printed that exact line too, each with rc 0. Both parts merged into a single <p>, and in place of the newline that had divided them, pandoc wrote a space.

A check with od -c showed that each part file ends in one newline and nothing more. That single newline ends a line. It does not leave a blank line behind it.

Leaving a blank line between files

Keeping the parts apart takes an empty line where one file meets the next. The test used a third file, include-blank.md, and od -c showed that it holds a lone newline and no other byte. List it second of three in the cat command:

cat include-intro.md include-blank.md include-setup.md > include-joined-blank.md
cat include-joined-blank.md
pandoc -f commonmark -t html include-joined-blank.md

1. Join the three files. This cat command also exited with rc 0.
2. Print the result. This time an empty line divided the parts:

Intro for Jane Doe.

Setup steps for Doe Holdings.

3. Render it. The commonmark run printed:

<p>Intro for Jane Doe.</p>
<p>Setup steps for Doe Holdings.</p>

Two paragraphs came out. The markdown and commonmark_x runs on include-joined-blank.md printed the same two lines, again with rc 0.

Set that next to the run in the previous section. Just one byte separates the two joined inputs, the extra newline from include-blank.md, and under the three readers it split one paragraph into two.

If the parts link to one another, check relative paths across several files before you join them. Key names get the same three-reader treatment in a companion post, markdown keyboard keys.

Where Sashmark fits

Under the current Sashmark plan, editing lives inside the reading view, so you could mend a wrong date in place. Its idea of a Round-Trip: the save rewrites only the characters you touched. Rounding out that roadmap entry, Changes View would call out whatever an agent altered in the meantime once you return, git or no 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.