markdown
Language
Markdown is a lightweight markup language used to display content on the web in a simple way. It’s the most popular markup language because it’s the easiest to get started with.
Markdown has different “flavours” or implementations that are slightly different in syntax. Obsidian notes are based on Markdown and are saved as .md files.
Almost every web site we use regularly is written at least partially in some form of HTML. The problem is that HTML looks like this— not exactly the most friendly for reading OR writing.
The format called Markdown was created as a more readable and writable alternative to HTML, but it isn’t a direct replacement. Instead, it’s kind of like another layer entirely: you write in something that looks pretty much like human prose, with minimal marks that format the text in some way.
At some point, Markdown is rendered: this is what’s happening when you switch from source mode to Live Preview in Obsidian. This is also what’s happening when you blog— all the major blogging platforms take Markdown text and convert it into HTML. So HTML is better for displaying formatted text online, but Markdown is better when you’re writing and reading in plain, unformatted text.
From Obsidian for non-coders.
Syntax
Paragraphs
To create paragraphs in Markdown, use a blank line to separate blocks of text. Each block of text separated by a blank line is treated as a distinct paragraph.
This is a paragraph.
This is another paragraph.This is a paragraph.
This is another paragraph.
A blank line between lines of text creates separate paragraphs. This is the default behavior in Markdown.
Multiple blank spaces
Multiple adjacent blank spaces within and between paragraphs collapse into a single space when displayed in Reading view or on Obsidian Publish sites.
Multiple adjacent spaces
and multiple newlines between paragraphs.Multiple adjacent spaces
and multiple newlines between paragraphs.
If you want to prevent spaces from collapsing or add multiple blank spaces, you can use the (non-breaking space) or <br> (line break) HTML tags.
Line breaks
By default in Obsidian, pressing Enter once will create a new line in your note, but this is treated as a continuation of the same paragraph in the rendered output, following typical Markdown behavior. To insert a line break within a paragraph without starting a new paragraph, you can either:
- Add two spaces at the end of a line before pressing
Enter, or - Use the shortcut
Shift + Enterto directly insert a line break.
Why don’t multiple Enter presses create more line breaks in reading view?
Obsidian includes a Strict Line Breaks setting, which makes Obsidian follow the standard Markdown specification for line breaks.
To enable this feature:
- Open Settings.
- Go to the Editor tab.
- Enable Strict Line Breaks.
When Strict Line Breaks is enabled in Obsidian, line breaks have three distinct behaviors depending on how the lines are separated:
Single return with no spaces: A single Enter with no trailing spaces will combine the two separate lines into a single line when rendered.
line one
line twoRenders as:
line one line two
Single return with two or more trailing spaces: If you add two or more spaces at the end of the first line before pressing Enter, the two lines remain part of the same paragraph, but are broken by a line break (HTML <br> element). We’ll use two underscores to stand in for spaces in this example.
line three__
line fourRenders as:
line three
line four
Double return (with or without trailing spaces): Pressing Enter twice (or more) separates the lines into two distinct paragraphs (HTML <p> elements), regardless of whether you add spaces at the end of the first line.
line five
line sixRenders as:
line five
line six
Headings
To create a heading, add up to six # symbols before your heading text. The number of # symbols determines the size of the heading.
# This is a heading 1
## This is a heading 2
### This is a heading 3
#### This is a heading 4
##### This is a heading 5
###### This is a heading 6This is a heading 1
This is a heading 2
This is a heading 3
This is a heading 4
This is a heading 5
This is a heading 6
Bold, italics, highlights
Text formatting can also be applied using Editing shortcuts.
| Style | Syntax | Example | Output |
|---|---|---|---|
| Bold | ** ** or __ __ | **Bold text** | Bold text |
| Italic | * * or _ _ | *Italic text* | Italic text |
| Strikethrough | ~~ ~~ | ~~Striked out text~~ | |
| Highlight | == == | ==Highlighted text== | Highlighted text |
| Bold and nested italic | ** ** and _ _ | **Bold text and _nested italic_ text** | Bold text and nested italic text |
| Bold and italic | *** *** or ___ ___ | ***Bold and italic text*** | Bold and italic text |
Formatting can be forced to display in plain text by adding a backslash \ in front of it.
This line will not be bold
\*\*This line will not be bold\*\*This line will be italic and show the asterisks
\**This line will be italic and show the asterisks*\*Internal links
Obsidian supports two formats for internal links between notes:
- Wikilink:
[[Three laws of motion]] - Markdown:
[Three laws of motion](Three%20laws%20of%20motion.md)
External links
If you want to link to an external URL, you can create an inline link by surrounding the link text in brackets ([ ]), and then the URL in parentheses (( )).
[Obsidian Help](https://help.obsidian.md)You can also create external links to files in other vaults, by linking to an Obsidian URI.
[Note](obsidian://open?vault=MainVault&file=Note.md)Escape blank spaces in links
If your URL contains blank spaces, you must escape them by replacing them with %20.
[My Note](obsidian://open?vault=MainVault&file=My%20Note.md)You can also escape the URL by wrapping it with angled brackets (< >).
[My Note](<obsidian://open?vault=MainVault&file=My Note.md>)External images
You can add images with external URLs, by adding a ! symbol before an external link.
You can change the image dimensions, by adding |640x480 to the link destination, where 640 is the width and 480 is the height.
If you only specify the width, the image scales according to its original aspect ratio. For example:
Tip
If you want to add an image from inside your vault, you can also embed an image in a note.
Quotes
You can quote text by adding a > symbols before the text.
> Human beings face ever more complex and urgent problems, and their effectiveness in dealing with these problems is a matter that is critical to the stability and continued progress of society.
\- Doug Engelbart, 1961Human beings face ever more complex and urgent problems, and their effectiveness in dealing with these problems is a matter that is critical to the stability and continued progress of society.
- Doug Engelbart, 1961
Tip
You can turn your quote into a callout by adding [!info] as the first line in a quote.
Lists
You can create an unordered list by adding a -, *, or + before the text.
- First list item
- Second list item
- Third list item- First list item
- Second list item
- Third list item
To create an ordered list, start each line with a number followed by a . or ) symbol.
1. First list item
2. Second list item
3. Third list item- First list item
- Second list item
- Third list item
1) First list item
2) Second list item
3) Third list item- First list item
- Second list item
- Third list item
You can use shift + enter to insert a line break within an ordered list without altering the numbering.
1. First list item
2. Second list item
3. Third list item
4. Fourth list item
5. Fifth list item
6. Sixth list itemTask lists
To create a task list, start each list item with a hyphen and space followed by [ ].
- [x] This is a completed task.
- [ ] This is an incomplete task.- This is a completed task.
- This is an incomplete task.
You can toggle a task in Reading view by selecting the checkbox.
Tip
You can use any character inside the brackets to mark it as complete.
- [x] Milk
- [?] Eggs
- [-] Eggs- Milk
- Eggs
- Eggs
Nesting lists
You can nest any type of list—ordered, unordered, or task lists—under any other type of list.
To create a nested list, indent one or more list items. You can mix list types within a nested structure:
1. First list item
2. Ordered nested list item
3. Second list item
- Unordered nested list item- First list item
- Ordered nested list item
- Second list item
- Unordered nested list item
Similarly, you can create a nested task list by indenting one or more list items:
- [ ] Task item 1
- [ ] Subtask 1
- [ ] Task item 2
- [ ] Subtask 1- Task item 1
- Subtask 1
- Task item 2
- Subtask 1
Use Tab or Shift+Tab to indent or unindent selected list items to easily organize them.
Horizontal rule
You can use three or more stars ***, hyphens ---, or underscore ___ on its own line to add a horizontal bar. You can also separate symbols using spaces.
***
****
* * *
---
----
- - -
___
____
_ _ _Code
You can format code both inline within a sentence, or in its own block.
Inline code
You can format code within a sentence using single backticks.
Text inside `backticks` on a line will be formatted like code.Text inside backticks on a line will be formatted like code.
If you want to put backticks in an inline code block, surround it with double backticks like so: inline code with a backtick ` inside.
Code blocks
To format code as a block, enclose it with three backticks or three tildes.
```
cd ~/Desktop
```
~~~
cd ~/Desktop
~~~
cd ~/DesktopYou can also create a code block by indenting the text using Tab or 4 blank spaces.
cd ~/DesktopYou can add syntax highlighting to a code block, by adding a language code after the first set of backticks.
```js
function fancyAlert(arg) {
if(arg) {
$.facebox({div:'#foo'})
}
}
```function fancyAlert(arg) {
if(arg) {
$.facebox({div:'#foo'})
}
}Obsidian uses Prism for syntax highlighting. For more information, refer to Supported languages.
Note
Source mode and Live Preview do not support PrismJS, and may render syntax highlighting differently.
Footnotes
You can add footnotes[1] to your notes using the following syntax:
This is a simple footnote[^1].
[^1]: This is the referenced text.
[^2]: Add 2 spaces at the start of each new line.
This lets you write footnotes that span multiple lines.
[^note]: Named footnotes still appear as numbers, but can make it easier to identify and link references.You can also inline footnotes in a sentence. Note that the caret goes outside the brackets.
You can also use inline footnotes. ^[This is an inline footnote.]Note
Inline footnotes only work in reading view, not in Live Preview.
Comments
You can add comments by wrapping text with `inline This is a block comment.
Block comments can span multiple lines. %%
### Escaping Markdown Syntax
In some cases, you may need to display special characters in Markdown, such as `*`, `_`, or `#`, without triggering their formatting. To display these characters literally, place a backslash (`\`) before them.
Common characters to escape
- Asterisk: `\*`
- Underscore: `\_`
- Hashtag: `\#`
- Backtick: `` \` ``
- Pipe (used in tables): `\|`
- Tilde: `\~`
```md
\*This text will not be italicized\*.
This text will not be italicized.
When working with numbered lists, you may need to escape the period after the number to prevent automatic list formatting. Place the backslash (\) before the period, not before the number.
1\. This won't be a list item.- This won’t be a list item.
Tables
You can create tables using vertical bars (|) to separate columns and hyphens (-) to define headers. Here’s an example:
| First name | Last name |
| ---------- | --------- |
| Max | Planck |
| Marie | Curie || First name | Last name |
|---|---|
| Max | Planck |
| Marie | Curie |
While the vertical bars on either side of the table are optional, including them is recommended for readability.
In Live Preview, you can right-click a table to add or delete columns and rows. You can also sort and move them using the context menu.
You can insert a table using the Insert Table command from the Command Palette or by right-clicking and selecting Insert → Table. This will give you a basic, editable table:
| | |
| --- | --- |
| | |Note that cells don’t need perfect alignment, but the header row must contain at least two hyphens:
First name | Last name
-- | --
Max | Planck
Marie | CurieFormat content within a table
You can use basic formatting syntax to style content within a table.
| First column | Second column |
|---|---|
| Internal links | Link to a file within your vault. |
| Embed files |  |
Vertical bars in tables
If you want to use aliases, or to resize an image in your table, you need to add a \ before the vertical bar.
First column | Second column
-- | --
[[Basic formatting syntax\|Markdown syntax]] | ![[Engelbart.jpg\|200]]| First column | Second column |
|---|---|
| Markdown syntax | |
Align text in columns by adding colons (:) to the header row. You can also align content in Live Preview via the context menu.
Left-aligned text | Center-aligned text | Right-aligned text
:-- | :--: | --:
Content | Content | Content| Left-aligned text | Center-aligned text | Right-aligned text |
|---|---|---|
| Content | Content | Content |
Diagram
You can add diagrams and charts to your notes, using Mermaid. Mermaid supports a range of diagrams, such as flow charts, sequence diagrams, and timelines.
Tip
You can also try Mermaid’s Live Editor to help you build diagrams before you include them in your notes.
To add a Mermaid diagram, create a mermaid code block.
```mermaid
sequenceDiagram
Alice->>+John: Hello John, how are you?
Alice->>+John: John, can you hear me?
John-->>-Alice: Hi Alice, I can hear you!
John-->>-Alice: I feel great!
```sequenceDiagram Alice->>+John: Hello John, how are you? Alice->>+John: John, can you hear me? John-->>-Alice: Hi Alice, I can hear you! John-->>-Alice: I feel great!
```mermaid
graph TD
Biology --> Chemistry
```graph TD Biology --> Chemistry
Linking files in a diagram
You can create internal links in your diagrams by attaching the internal-link class to your nodes.
```mermaid
graph TD
Biology --> Chemistry
class Biology,Chemistry internal-link;
```graph TD Biology --> Chemistry class Biology,Chemistry internal-link;
Note
Internal links from diagrams don’t show up in the Graph view.
If you have many nodes in your diagrams, you can use the following snippet.
```mermaid
graph TD
A[Biology]
B[Chemistry]
A --> B
class A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z internal-link;
```graph TD A[Biology] B[Chemistry] A --> B class A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z internal-link;
This way, each letter node becomes an internal link, with the node text as the link text.
Note
If you use special characters in your note names, you need to put the note name in double quotes.
class "⨳ special character" internal-link
Or, A["⨳ special character"].
For more information about creating diagrams, refer to the official Mermaid docs.
Math
You can add math expressions to your notes using MathJax and the LaTeX notation.
To add a MathJax expression to your note, surround it with double dollar signs ($$).
$$
\begin{vmatrix}a & b\\
c & d
\end{vmatrix}=ad-bc
$$You can also inline math expressions by wrapping it in $ symbols.
This is an inline math expression $e^{2i\pi} = 1$.This is an inline math expression .
For more information about the syntax, refer to MathJax basic tutorial and quick reference.
For a list of supported MathJax packages, refer to The TeX/LaTeX Extension List.
Learn more
To learn more about how Obsidian parses Markdown, refer to Obsidian Flavored Markdown.