Question: How to embed Markdown files?

[nlohmann]

I have a script that creates some Markdown file (say, output.md) and I would like to include this file in another file (say, `README.md).

I tried the following in REAMDE.md:

This is the output of the build step:

<!-- embedme some/dir/output.md -->

but this seems to have no result.

If I add a code fence below, I get the warning

Output snippet for file some/dir/output.md contains a code fence. Refusing to embed as that would break the document

The warning is correct, as the file to be included indeed contains a code fence. But I would like to embed it as-is - not within a code fence.

Is this possible?

(Sorry for opening so many issues, but this tool is so cool, and it really helps us cleaning up the documentation of a large project!)

[zakhenry]

Hmm yea I've been thinking about this a bunch and agree it would be an excellent addition, however I'm a little stumped on how to implement in in an ergonomic way.

The problem is that one of the core design goals of embedme is that it is idempotent - you should be able to rerun the tool after previously running it and get the exact same output. This is easy when there are code fences as it is clear where the embed should finish and the tool should start looking for the next embed point. If the tool was able to embed markdown in a raw fashion, if the tool was to be rerun after the embedded snippet was edited it would be unclear where the embed started and ended.

This kinda leaves us with two options

1. Make embedded markdown forced to be within an hr fence

<!-- embedme path/to/partial.md -->
---
## partial content goes here
---

This has the obvious disadvantage that all partials would be framed by a horizontal rule

or

2. Explicitly mark the beginning and end

<!-- embedme @include path/to/partial.md -->
## partial content goes here
<!-- embedme @includeEnd -->

Did I miss an option? I think I have a preference for the second one despite it's verbosity

PS, no problem, I love getting issues as it means the tool is somewhat useful 😁

[nlohmann]

I see. I also can't think of a better way than the second solution.

[Botosio]

I see. I also can't think of a better way than the second solution.

Has this been implemented?

[zakhenry]

@Botosio nope not yet, I'm open to PRs though!