Markdown: Your Go-To for Formatted Easy Writing
Why Markdown Matters
If you’re like me – building workflows, writing model cards, managing notes in Obsidian – you’ve probably run into the usual formatting trap: switch editors, fight HTML tags, lose portability. That’s where Markdown comes in. Write in plain text, stay readable, and still output to pretty web pages.
What Is Markdown?
Markdown is a lightweight markup language created in 2004 by John Gruber (with help from Aaron Swartz) with the express goal: “to write using an easy-to-read and easy-to-write plain text format, optionally convert it to structurally valid XHTML (or HTML)”.
At its heart: stay readable as raw text, don’t look like you’re embedding tags everywhere. It works beautifully for blogging, documentation, notes, and yes — AI model cards too.
Origins & Timeline
- 2004: Gruber releases Markdown.
- Early inspiration: plain-text email conventions, Usenet markup, lightweight markup languages like Setext, Textile, reStructuredText.
- As Markdown gained adoption, variants and extensions popped up (tables, footnotes, task lists).
- Because of divergence, efforts emerged (e.g., CommonMark) to standardise behaviour across implementations.
- Today: widely used in blogs, code repos (README.md), Obsidian vaults, static-site generators, wikis.
Why I Use Markdown
- I write in Obsidian. That means: plain-text, version-control friendly, fast.
- I publish model cards for AI models. Markdown gives me a standard across sites, minimal fuss.
- My website uses WP + plugin. I can author in Markdown, hit publish, done.
- Portable. If I switch to another tool tomorrow, my notes and docs carry over.
- Readable-by-humans in source form. If I open a
.mdfile, I don’t immediately dread a wall of<div>tags.
Markdown Syntax Cheat-Sheet
HEADINGS
Headings use the hash symbol (#). The number of hashes corresponds to the heading level (H1 through H6).
# Heading 1
## Heading 2
### Heading 3When rendered, the Markdown code block above will display as the examples shown below.
Heading 1
Heading 2
Heading 3
EMPHASIS
You can make text bold, italic, or ~~strikethrough~~ using underscores, asterisks or tildes.
_italic sample_
*also italic*
**bold sample**
***bold italic***
~~strikethrough~~When rendered, the Markdown code block above will display as the examples shown below.
italic sample
also italic
bold sample
bold italic
strikethrough
LISTS
Lists can be unordered (bullet points), ordered (numbered), or even task lists.
Unordered Lists (Bullets)
Use an asterisk (*), plus sign (+), or hyphen (-).
* Item one
* Item two
* Sub-item A
* Sub-item B
* Item threeWhen rendered, the Markdown code block above will display as the examples shown below.
- Item one
- Item two
- Sub-item A
- Sub-item B
- Item three
Ordered Lists (Numbered)
Use a number followed by a period (1.). The specific number doesn’t matter for the output (they just need to start with 1.), but it’s good practice to keep them sequential.
1. First step
3. Second step
2. Third step
1. Sub-step 1
2. Sub-step 2When rendered, the Markdown code block above will display as the examples shown below.
- First step
- Second step
- Third step
- Sub-step 1
- Sub-step 2
Task Lists
Task lists allow you to create a list of items where each item can be marked as complete or incomplete. They start like a regular list but include [ ] (incomplete) or [x] (complete) inside the list item.
- [ ] Research new Stable Diffusion model concepts
- [x] Draft Markdown article
- [ ] Prepare YouTube video script for promotion
- [ ] Check Print-on-Demand mockups
- [x] Review t-shirt designs
- [ ] Finalize mug layoutsWhen rendered, the Markdown code block above will display as the examples shown below.
- [ ] Research new Stable Diffusion model concepts
- [x] Draft Markdown article
- [ ] Prepare YouTube video script for promotion
- [ ] Check Print-on-Demand mockups
- [x] Review t-shirt designs
- [ ] Finalize mug layouts
LINKS & IMAGES
Links use brackets [] for the text and parentheses () for the URL. Images are just like links but start with an exclamation mark !
[A link to the image](https://image.tensorartassets.com/cdn-cgi/image/anim=true,plain=false,w=120,f=avif,q=85/users/common/avatar/639678612429250130/4cf78912-d051-c0bf-d29a-958f1d298b2d.png)When rendered, the Markdown code block above will display as the examples shown below.
BLOCKQUOTES
Blockquotes are great for citing sources or highlighting specific text. Use the greater-than symbol >
> This text is a blockquote. This text is a blockquote.
> Markdown is a lightweight markup language...
> -- John Gruber Markdown is a lightweight markup language…
– John Gruber
CODE
Code can be displayed inline or in a block.
Inline Code
Use a single backtick (`) to wrap short code snippets.
Inline code uses `single backticks` to highlight a function.When rendered, the Markdown code block above will display as the examples shown below.
Inline code uses single backticks to highlight a function.
Code Blocks
Use three backticks (```) on the lines before and after your code. You can optionally specify the language for syntax highlighting.
```python
def generate_ai_asset(prompt):
# This is a Python function for a model card
print(f"Generating asset for: {prompt}")
return True
```def generate_ai_asset(prompt):
# This is a Python function for a model card
print(f"Generating asset for: {prompt}")
return True
TABLES
Tables are created using pipes (|) to define columns and hyphens (-) for the header separator. You can also specify alignment using colons (:).
You can control the text alignment within columns by adding colons to the header separator line:
| Alignment Syntax | Example Output |
| Left-aligned: | :— |
| Center-aligned: | :—: |
| Right-aligned: | —: |
| Parameter | Value | Notes |
| :--- | :---: | ---: |
| Model Name | Stoke-V1.0 | Left-aligned Parameter |
| Training Steps | 1000 | Center-aligned Value |
| File Size (GB) | 3.5 | Right-aligned Notes |When rendered, the Markdown code block above will display as the examples shown below.
| Parameter | Value | Notes |
|---|---|---|
| Model Name | Stoke-V1.0 | Left-aligned Parameter |
| Training Steps | 1000 | Center-aligned Value |
| File Size (GB) | 3.5 | Right-aligned Notes |
LINE BREAK
Use three or more hyphens (-), asterisks (*), or underscores (_) on a line by themselves. They must have a blank line before the line they are used on.
some content here
---
some **MORE** content here
***
You ~~gessed~~ guessed it - even more content
___
***END*** --- end --- _eNd_ --- ~~start~~ --- *EnD* --- ***END*** --- end --- _eNd_ --- ~~start~~ --- *EnD*When rendered, the Markdown code block above will display as the examples shown below.
some content here
some MORE content here
You gessed guessed it – even more content
END — end — eNd — start — EnD — END — end — eNd — start — EnD
FINAL THOUGHTS
Markdown is deceptively simple. It doesn’t try to be everything at once—just “good enough” to write plain text with formatting. That minimalism is its power. For someone building workflows in Obsidian, habitual note taking, writing blog posts, it gives a consistent, portable base.
Lean into Markdown. Write once, publish many ways. Stay agile. Stay readable. Stay Stoked.
Discover more from Stoke McToke
Subscribe to get the latest posts sent to your email.