Markdown
10/17/2022
Friends, bloggers, content creators, prolific note takers, software developers, lend me your screens!
It's time we take a journey into the exciting, user-friendly world of Markdown.
It’s a lightweight markup language, sharing its lineage with the likes of HTML, but without the complexity and fuss.
A magical tool for formatting text, Markdown embraces simplicity, making it a boon for those who crave clarity.
Your blog posts, comments, and documentation (and the people who read them) will thank you for learning Markdown.
Markdown is a staple I use in Obsidian and GitHub (for code repositories and pull requests) and because I use it so much, I wanted to write an in depth post to help others see how useful it is and how to get started!
Prerequisites
Before we voyage further, let's take stock. This guide assumes:
- A basic understanding of digital text files.
- Familiarity with a text editor (VS Code and Obsidian to name a few).
- An unquenchable thirst for clean, fuss-free, beautiful text formatting.
Lack a prerequisite or two? Fear not! There's always time to get up to speed.
Once you've acquired these basics, Markdown will be waiting for you, with open arms and simple syntax.
Objective
Our mission is twofold:
- To illuminate the advantages of Markdown and its commitment to plain text.
- To explore the uncomplicated syntax that is the beating heart of Markdown.
With these objectives in mind, we stride forward into a world of clarity, simplicity, and text-editing ease.
May the following sections serve as your roadmap on this enlightening journey.
The Simplicity of Markdown is a Superpower
What's Markdown, you ask? Simply put, Markdown is a plain-text formatting syntax that prioritizes readability and ease of use.
Conceived by John Gruber and Aaron Swartz in 2004, Markdown has been winning hearts worldwide, and it's high time you joined the club.
But why is Markdown such a phenomenon? Let's break it down:
Plain Text Paradise
Markdown thrives on simplicity.
Being a plain-text language, it strips away the fuss, letting your content shine.
And unlike HTML or other markup languages, Markdown won't have you wrestling with intricate tags.
It's all about clean, comprehensible content.
Portability Powerhouse
With Markdown, you're not chained to specific software or platform.
Since it's plain text, you can edit it anywhere, from your basic editors such as Emacs, Vim, Nano or Notepad to advanced text editors like VS Code and my trusty sidekick: Obsidian.
The compatibility extends to operating systems too – Windows, macOS, Linux, you name it.
Extensibility Extraordinaire
Markdown's flexibility is its secret weapon.
Its core syntax covers most formatting needs, but when you want more, extensions come to your rescue.
With extended syntax, you can create tables, footnotes, and even task lists.
Platforms like GitHub and Discourse have their custom Markdown extensions, pushing the boundaries of what's possible.
Why Use It?
So why should you use Markdown?
Well, if simplicity, portability, and extensibility haven't convinced you, think of the future.
As technology advances, your content should stand the test of time.
With Markdown, you're making a future-proof choice.
Its text-based nature ensures your content remains accessible, no matter where technology takes us.
Markdown is not just a markup language; it's a philosophy, a commitment to clarity over complexity.
So whether you're a blogger, a developer, or someone who just loves well-formatted text, Markdown is your ticket to a smoother, simpler writing experience.
Syntax Overview
Marvelous Markdown, in its sublime simplicity, revolves around a few fundamental elements. Let's do a quick run-through of the syntax.
Headings
Headings, in any form of writing, serve as indispensable navigational aids. Headings provide a skeletal framework to your content, dividing it into digestible sections. Readers can perceive the structure of your text at a glance, making it less intimidating and easier to comprehend.
A heading in in Markdown is denoted by 1 to 6 # followed by a space followed by the heading content.
The rules that make a valid heading:
- the first character in a line is
#with up to 6 total# - a space immediately following the
# - one or more characters
Valid Examples
# Heading Level 1
## Heading Level 2
### Heading Level 3
###### Heading Level 6
Invalid Examples
This is invalid because there's no space:
#Heading
This is invalid because the first character is not a # (in this case it's a space even though you can't see it):
# Heading
Emphasis
In the realm of communication, be it spoken or written, emphasis serves as a crucial tool.
It's how we add flavor to our language, making it more expressive and nuanced.
In Markdown, emphasis takes the form of italics and bold text, both of which serve distinct but interconnected purposes.
Using emphasis strategically in your Markdown text makes it not only more engaging, but also more effective in conveying your intended meaning.
It helps guide the reader's attention, provides clarity, and enriches the reading experience.
Remember, the spice of emphasis makes the meal of content all the more savory!
Rules for Emphasis
The rules that make a valid emphasis:
- Use single asterisks or underscores for italics:
*italic*or_italic_. - Double them up for bold:
**bold**or__bold__. - A combo will give you bold italics:
**_bold and italic_**. - The
*or_must have a space on the outside edge or be at the beginning or end of a line
Valid Examples
*italic* or _italic_
**bold** __bold__
*__bold and itailc__*
Invalid Examples
Some tools may treat this as valid markdown but there are a number of them that do not. If you decide to use these invalid examples, just know they could cause problems!
*italic*should not work
**bold**should not work
Lists
Lists, whether they're bulleted or numbered, are essential elements of efficient writing, and Markdown makes creating them a cinch
Lists help structure and organize complex information into manageable, bite-sized chunks. This structure enhances the clarity of your content, making it easier for readers to absorb and understand.
Numbered (or ordered) lists can be used to emphasize a sequence or a set of steps. They can also denote a hierarchy of importance among different points.
In today's fast-paced world, readers often scan content to find the information they need. Lists stand out visually, making scanning more efficient.
Rules for Lists
- Use an asterisk, plus sign, or hyphen for unordered lists:
* Item,+ Item, or- Item. - A number followed by a dot offers an ordered list:
1. First item. - You can nest lists by indenting
- You can use lists for tasks
Example of Lists in Markdown
- asterisks are great
- they make lists easy
- lists can be nested
1. There is
2. priority in
3. my lists
Links and Images
Links are where tools like Obsidian really shine.
There are two different syntaxes for links:
- Square brackets around the link text and parentheses around the URL give you a link:
[Link text](URL). - Double square brackets around the link text is for wiki style links:
[[Wiki style link]]. These are at the core of Obsidian's graph system
There are two different syntaxes for images:
- An exclamation mark before a link syntax provides an image:
. I wrote an indepth post on how to combine a link and a markdown link in Set An Anchor Link On An Image In Markdown. - An exclamation mark before the double square brackets for wiki style:
![[My Image.<EXTENSION>]]. I use this syntax in Obsidian.
Code
As someone who writes a lot of code, I lean heavily on inline code and code blocks (all of the markdown examples above are in code blocks).
Rules for Code
- Use single backticks around inline code:
`code`. - Use triple backticks (also known as "fence") to create a block of code:
```code```. - For code blocks, most renderers allow you to add meta data to the first "fence".
Example of Code Block in Markdown
\`\`\`javascript
function sayHello() {
// do some stuff
}
\`\`\``
Horizontal Rules
In Markdown, horizontal rules serve as visual separators, efficiently breaking up different sections or ideas in your content to enhance readability.
They offer a clear pause, aiding in the organization and structure of your text, thereby improving the overall user experience.
Rules for a horizontal rule
- must be three
-characters like this:--- - must be the first character on a line
Example of Horizontal Rules in Markdown
Text above
---
Text below
Block Quotes
Block quotes in Markdown provide an effective way to highlight or separate quotations, anecdotes, or significant pieces of information from the main body of text.
This distinct visual emphasis enhances the reader's focus and comprehension, enabling them to understand the importance or relevance of the quoted text.
Rules for block quotes
>must be the first character of the line>must be followed by a space, then followed by the text
Example of Blockquote in Markdown
> I may not have gone where I intended to go, but I think I have ended up where I needed to be.
> - Douglas Adams
Tables
Tables in Markdown offer a structured format for presenting data or information that is best understood in a comparative or relational manner.
By organizing content in rows and columns, tables enhance readability, allowing readers to easily digest and comprehend complex sets of data.
Rules for Tables
Tables are probably the element with the most complex markdown syntax.
The rules for
Example of Tables in Markdown
| Column 1 | Column 2 |
| -------- | -------- |
| Cell 1 | Cell 2 |
Extended Syntax
There are a few editors that support extended syntax.
Obsidian and GitHub in particular support much more robust syntaxes. I've written a few posts (in the Markdown#Relevant Posts section).
Summary: Markdown Magic, Decoded
Let's take a moment to reflect on our journey.
We've delved into the marvels of Markdown, a potent yet straightforward markup language that makes text formatting a breeze.
Here are the highlights:
- Markdown advocates simplicity, freeing you from the intricate shackles of more complex markup languages.
- Its plain text approach makes your content portable, platform-agnostic, and future-proof.
- Markdown's intuitive syntax enables you to add emphasis, create lists, and more, all with a handful of characters.
But our expedition has only just begun.
As you master Markdown's syntax and start to apply these skills, you'll unlock newfound efficiency and precision.
It's a passport to a world where formatting is no longer a chore, but a joy.
So, equip yourself with the knowledge shared, and set forth into the vast universe of content creation.
With Markdown as your trusted ally, your journey will be smooth, seamless, and stylish.
Upwards and onwards, dear reader!