What is Markdown

Markdown is a plain text syntax that maps directly to HTML decoupling formating and copy. This allows content for be styled via css enhabling design freedom.

Markdown also integrates seamlessly with most if not all programing languages thereby enhabling transforming, sorting, and search etc in a much more straight forward way compared to traditional wysiwyg editors such as word, paper, and gdocs.

CheatSheet

Basic Syntax

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

Extended Syntax

Headings

# H1 - Header One
## H2 - Header Two
### H3 - Header Three
#### H4 - Header Four
##### H5 - Header Five
###### H6 - Header Six

HTML Result

<h1>H1 - Heading One</h1>
<h2>H2 - Heading Two</h2>
<h3>H3 - Heading three</h3>
<h4>H4 - Heading Four</h4>
<h5>H5 - Heading Five</h5>
<h6>
  H6 - Heading Six
</h6>

Visual Example

H1 - Heading One

H2 - Heading Two

H3 - Heading three

H4 - Heading Four

H5 - Heading Five

H6 - Heading Six

Text Styles

Some default text - Once upon a time in the land of England, there lived a web developer with too much time on their hands.
**some strong text**
*some italic text*

Other Text Styles

~~some strikethrough~~
==some highlighted words==

HTML Result

<p>
  Some default text - Once upon a time in the land of England, there lived a web
  developer with too much time on their hands.
</p>
<p><strong>some strong text</strong></p>
<p><em>some italic text</em></p>

Visual Example

Once upon a time in the land of England, there lived a web developer with too much time on their hands.

some strong text some italic text

Markdown Tool and Apps

Because markdown is written in plain text any text editor can be used to write markdown but there are some app nativily support a enhanced markdown experience.

• vscode
• obsidian
• typora
• paper writing app

VSCode

VSCode is an best in show text editor since 2016 primarlly tailored to programming but because of the modular plugin focused architeture of the app it can be easily configured to be a top teir markdown editor.

Vscode Extensions for Markdown

• Markdown all in one
• Markdown Emoji
• Markdown PDF
• Markdown preview mermaid support

Obsidian

Obsidian has gained a huge following since 2022 after it's initial lunch in 2020. It is considered a knowleged base tool or "second brain" with many features and plugins enhabiling organizing data and the relationships between.

Note: Though Obsidian sits on the file system it leverages a .obsidian directory to manage plugin configs and states, which can cause issue when used in a development pipeline.

I personaly ran into some complexity layering it on top of a Gatsby development workflow with managing the content. I suspect there is a workaround but it was not a priority.

Typora

Typora is a text editor tailor for markdown focused on a clean, writing experience. It sits on top of the file system enabling seamless navigation on and organization of a content directory with directory tree view.

A notable quality of life feature is that typora enables custom css stylesheets allowing completely customizable writing enviroment.

Paper Writing App

Paper is a polished markdown writing experience best in show for working with a single file.

Reference

VSCode custom markdown config

setting.json

{
  ...
 "[markdown]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.unicodeHighlight.ambiguousCharacters": false,
    "editor.unicodeHighlight.invisibleCharacters": false,
    "editor.rulers": [70],
    "editor.wordWrap": "wordWrapColumn",
    "editor.wrappingIndent": "same",
    "editor.quickSuggestions": {
      "comments": "off",
      "strings": "off",
      "other": "off"
    },
    ...
}

Setting Readable Line width

{
  ...
 "[markdown]": {
   ...
    "editor.rulers": [70],
    "editor.wordWrap": "wordWrapColumn",
    "editor.wrappingIndent": "same",
    ...
 }
    ...
}