InkMomentum

Markdown · By Seth ·

Markdown syntax and app features: what travels with your file?

A Markdown document can look right in one app and lose something when you open it somewhere else. The words are still there. The checkboxes may be plain characters. The note links may stop opening. A table may look like a small fence made of pipes.

Usually, the file has not stopped being Markdown. The two tools support different features.

The useful question is: which parts of this document depend on the app?

Begin with a small example

This document uses familiar Markdown structure:

# Website review

## Questions

- Is the introduction clear?
- Does the example need more context?

Read the [project brief](project-brief.md).

Headings, ordinary lists, and links belong to the CommonMark syntax described in its specification. Whether the link opens a local file still depends on the viewer and its access to that file.

That distinction matters. Recognizing the syntax and making its destination available are separate jobs.

Now add this:

- [ ] Review the introduction
- [x] Check the image captions

Those are task-list items in GitHub Flavored Markdown. They are an extension. A tool can support Markdown without turning those characters into checkboxes. Even when it draws a checkbox, that does not necessarily connect the item to a task manager, a reminder, or a notification.

Ask what the app is adding

Some features are easy to spot because they have special syntax. Others hide behind a familiar interface.

A file may contain a wiki-style link such as [[Project brief]]. The app might find a note by title, update the link when the note is renamed, or show a preview on hover. Another viewer may not know what to do with it.

The same principle applies to queries, embeds, and callouts. If the feature needs the application’s index or a plugin to work, copying the text alone may not reproduce the behavior.

That can be a perfectly reasonable tradeoff. The mistake is discovering it after moving hundreds of documents.

Make a sample that resembles your work

Create a small test document with the features you actually use. Include one image and one link to a neighboring document. Add your usual tables, task lists, or metadata if you depend on them.

Open it in the destination tool. Read the source, inspect the preview, and click the links. Ask three questions:

Those are different levels of success. A note can pass the first and fail the other two.

Record anything that needs adjustment. Perhaps you can replace one app-specific link with a regular file link. Perhaps a table needs a supported extension. Perhaps you decide the feature is useful enough to keep and document its requirements.

Choose with the document’s future in mind

A private working note and a template you share publicly have different needs. In your own notes, a specialized feature may save enough time to justify the dependency. In a public template, simpler syntax gives more readers a usable starting point.

I would keep a shared template modest and label any extensions it requires. That makes the file easier to trust, and it saves the reader from thinking they did something wrong.

Try this with one document before changing your whole collection. A little compatibility testing is far less work than reconstructing a broken setup later.

Sources

Keep exploring

Read the Markdown cheat sheet for more examples.

All writing