Markdown is an amazing authoring format. It frees us from the shackles of Microsoft word and let's you focus primarily on the content.

As a developer, you will write ALOT of markdown over the course of your career.

But like any text document, .md docs can grow stale over time. As a project grows, we forget what docs we've authored and what information we've added into the docs we did write.

It's understandable. We can't keep it all in our head. But this can lead to a terrible downstream developer experience.

When you have dead links, or worse, outdated information in your docs it can really rub folks the wrong way. We've all been there when we've been led down a rabbit hole of outdated information. (╯°□°)╯︵ ┻━┻

We can do better.

Addressing documentation drift

What if we could reference the source of truth in our docs and have them automatically update if something changes?

Enter markdown magic.

Markdown magic utilizes html comment blocks to mark where remotely referenced contents lives. These HTML comments are invisible to the reader but are used as markers for the markdown magic library to know where to pull in the remote content.

These automagic invisible references can be used to pull in remote content from a URL, a file, or even a database and automatically update during your CI flow.

A block is defined like this

<!-- doc-gen {transformName} [options] -->
[content to be replaced]
<!-- end-doc-gen -->

The opening <!-- doc-gen {transformName} [options] --> comment tag is where you define the transformName to run to change the inner contents and where you define any options needed for the transform.

Then blocks are closed with <!-- end-doc-gen -->. The inner content of the block is replaced with the transformed content.

A real world example looks like this:

<!-- doc-gen remote url="https://github.com/DavidWells/markdown-magic/blob/master/my-remote-source-of-truth.md" -->
This will be replaced with the remote content via the `remote` transform
<!-- end-doc-gen -->

The result of the above block would be the content of the remote file like so

<!-- doc-gen remote url="https://github.com/DavidWells/markdown-magic/blob/master/my-remote-source-of-truth.md" -->
My amazing remote content
<!-- end-doc-gen -->

The text "My amazing remote content" would then be visible in the markdown file for any reader on Github or in your docs site and the surrounding comment is invisible.

Syncing in code

The remote transform is just one of many transforms available in markdown magic.

Here's another that uses the code transform. The code transform is similar but it will automatically wrap the code with syntax highlighting. You can pull in remote code or local code snippets via relative paths.

<!-- doc-gen code url="https://raw.githubusercontent.com/DavidWells/markdown-magic/master/examples/1_simple.js" -->
This transform will automatically pull in the code from the remote source and place it here in a markdown code fence
<!-- end-doc-gen -->

The result of the above block would be the content of the remote code like so

<!-- doc-gen code url="https://raw.githubusercontent.com/DavidWells/markdown-magic/master/examples/1_simple.js" -->
```js
console.log('Cool')
```
<!-- end-doc-gen -->

Custom transforms

There are several other pre-baked transforms to use or you can write your own.

Checkout some of the plugin examples for ideas on how you might be able to use this in your markdown workflow.

Compatibility

The library is compatible with whatever flavor of markdown you are using like MDX, markdoc, plain text files or regular ol' markdown.

Download

You can see more about the package on GitHub

Enjoy ✌️