You can use anything so long as it's markdown

In the corporate word, there is a reason why everyone uses microsoft word. It can go anywhere and everyone is expected to be able to open it. In tech, the closest equivalent would be markdown. So long as your content adheres closely to the standard, you can move it between systems seamlessly. If you do add additional platform specific syntax, it can help to keep a list of the special features that you use, so that you know how to convert the docs later. This post will go over the basic standard, where it is supported, and how to convert between markdown conventions.

The baseline format (kind of)

The most barebones markdown that you can get is considered to be that which is contained within John Gruber’s original spec sheet. This syntax should be supported everywhere. If you stick to this, you’ll have maximum portability.

### Heading

# H1
## H2
### H3

### Bold

**bold text**

### Italic

*italicized text*

### Blockquote

> blockquote

### Ordered List

1. First item
2. Second item
3. Third item

### Unordered List

- First item
- Second item
- Third item

### Code

`code`

### Horizontal Rule

---

### Link

[Markdown Guide](https://www.markdownguide.org)

### Image

![alt text](https://www.markdownguide.org/assets/images/tux.png)

Extended syntax

This is where things get a little adventurous. These aren’t supported everywhere, from my experience most applications have some of the following supported, but not all. Or, if they do support it, they use a different syntax.

### Table

| Syntax | Description |
| ----------- | ----------- |
| Header | Title |
| Paragraph | Text |

### Fenced Code Block

Three backticks (I can't nest a codeblock in a codeblock)

### Footnote

Here's a sentence with a footnote. [^1]

[^1]: This is the footnote.

### Heading ID

### My Great Heading 

Heading id's also cause issues with liquid, this is curly braces 
with a # sign in front of the id string.

### Definition List

term
: definition

### Strikethrough

~~The world is flat.~~

### Task List

- [x] Write the press release
- [ ] Update the website
- [ ] Contact the media

### Emoji

That is so funny! :joy:

### Highlight

I need to highlight these ==very important words==.

### Subscript

H~2~O

### Superscript

X^2^

Common tools and their flavours

GitHub

GitHub expands on Gruber’s work with GitHub flavoured markdown which is a superset of the original spec. This means that GitHub will support all of the basic syntax, plus adding some of it’s own.

Obisidian

Like GitHub, Obsidian supports all of the basic syntax, and adheres to most of the syntax for advanced formatting. They have defined their spec in Obisidian Flavoured Markdown. You shouldn’t have any issues taking documents out of Obsidian and porting them over into a new platform, provided you adhere to the basics.

Logseq

Logseq supports some common markdown syntax, but there are some caveats. Since Logseq is an outliner, it will start paragraphs with a -. Additionally, you may end up with a lot of [[]] in your documents due to linking between pages, and this feature may not be supported in other applications. The double brackets are fairly easy to isolate and replace, whereas the - can be a bit trickier.

mdBook

mdBook adheres to CommonMark, with a few notable extensions: strikethrough, footnotes, tables, and task lists.

mkDocs

mkDocs is largely compliant with the standard specification, with a few small differences. If you use the base mkDocs it is highly unlikely that these differences will ever cause problems. However, there are many themes which introduce their own syntax (the most popular being Material for Mkdocs) and this syntax is not transferable.

Switching applications with specialized syntax

Of course, one of the draws of many systems is using plugins or platform specific features—that’s why you’re on that platform in the first place. I want to stress that using these features is not wrong. All that matters is keeping track of which additional syntax you used, and which concept it emulates. For example, admonitions are a common addition, but are handled differently by most platforms.

Syntax can always be switched via a simple find and replace. The ease of performing that operation will depend on how well the syntax “sticks out in the crowd”. Let’s say that for admonitions, the syntax calls for three slashes, like this ///. The key question to ask is "how often am I going to write those three slashes in a situation that is not for an admonition. Additionally, are those slashes on their own line, or do they get nestled in with the rest of the text. The former is easier to replace, the latter, not so much.

Before making the switch, it may be helpful to first find how many files use the syntax in the first place. If it is just one or two, perhaps it is quicker to just make the change manually (or consider whether continuing to support the special syntax is worth it at all). This can be done with a simple grep command. Using the example of the three slashes

# Find all files in the current directory, output files name, recursive
grep -rl '^///' --include='*.md' .

Next, you can perform a find and replace with sed and find. Let’s say we wanted to replace all occurrences of /// with [!note]. First, you could use diff to preview the changes before executing.

find . -type f -name '*.md' | while read -r file; do
  echo "=== $file ==="
  diff <(cat "$file") <(sed 's|^///|[!note]|g' "$file")
done

Then, to actually execute the change

find . -type f -name '*.md' -exec sed -i 's|^///|[!note]|g' {} +

And with that, you have translated the special syntax to be able to migrate between tools easily. As with any large changes, it would help to have files tracked via git so you can always move between commits.

Conclusion

Writing in markdown makes it super easy to try out different notetaking applications, and never be locked in to one. Most software built around markdown also tends to be quite stable, and should last you a long time.