---
title: "Markdown include file: pandoc output for three forms"
slug: markdown-include-file
excerpt: "Under What the three readers printed, the pandoc output for each markdown include file form is quoted from the test log."
quickAnswer: "The input file appears as cat printed it in Three include forms in one input. Pandoc's HTML for that file is reported in What the three readers printed. A rerun with the named target present is covered in A real notes file beside the input. The command sequence appears in Joining files with cat before rendering. The comparison appears in Leaving a blank line between files."
keyTakeaways:
  - "See Three include forms in one input for the file exactly as cat showed it."
  - "Pandoc's HTML under three reader names is reported in What the three readers printed."
  - "For a rerun with notes/setup.md sitting next to the input, read A real notes file beside the input."
  - "A shell route to combine files first is laid out in Joining files with cat before rendering."
  - "Compare two joined inputs under Leaving a blank line between files."
publishedDate: 2026-10-21
dateModified: 2026-10-21
author: Bobby Huang
cluster: B
role: post
status: published
faq:
  - q: Will pandoc pull another Markdown file into mine?
    a: "Pandoc's lines for three include forms are quoted in What the three readers printed."
  - q: Does it change anything if the target file exists?
    a: "Under A real notes file beside the input, that rerun and its grep counts are shown."
  - q: How do I combine several Markdown files into one?
    a: "Numbered cat steps sit in Joining files with cat before rendering."
  - q: Why did my joined files run together?
    a: "Look in Leaving a blank line between files for the comparison."
related:
  - markdown-links-to-local-files
  - markdown-relative-paths-multiple-files
  - markdown-wikilinks
---

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](markdown-links-to-local-files.md).

## 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:

```text
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](markdown-wikilinks.md). 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:

```sh
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:

```html
<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 `&lt;` and `&gt;`.

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:

```text
Setup steps for Doe Holdings.
```

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

```sh
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:

```text
Intro for Jane Doe.
```

`cat include-setup.md` printed:

```text
Setup steps for Doe Holdings.
```

Follow these steps from the test folder:

```sh
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:

```text
Intro for Jane Doe.
Setup steps for Doe Holdings.
```

3. Render the joined file. Output under `commonmark`:

```html
<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:

```sh
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:

```text
Intro for Jane Doe.

Setup steps for Doe Holdings.
```

3. Render it. The `commonmark` run printed:

```html
<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](markdown-relative-paths-multiple-files.md) before you join them. Key names get the same three-reader treatment in a companion post, [markdown keyboard keys](markdown-keyboard-keys.md).

## 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](/features), the [help pages](/help) and the [roadmap](/roadmap) for where each part stands.

More at [sashmark.com](https://www.sashmark.com/).