Markdown Tutorial – Get Into Note-Taking With Obsidian

Auf Deutsch: Markdown-Tutorial – elegant einsteigen (generateCLICKS.DE)

If you don’t know Obsidian yet:
Your Note App For Everything, Forever

If you are looking for alternatives to Obsidian:
Your Digital Notebook (How To Find Your App)

If you are interested in what is new in Obsidian 1.0:
Obsidian 1.0.0 Is Here – What’s New?

Otherwise, here we go with the Markdown Tutorial.

Create new note

Before I go into the Markdown details one by one, let me give you a rough idea of how you can handle files in Obsidian.

After launching, Obsidian brutally reminds you that you haven’t written anything yet, until now.

I am actually still irritated by this home screen. I also still don’t know what that cross in front of “No file open” is for. It even has a hover effect when you move the mouse over it. But absolutely no consequences. Maybe there will be an update for this, soon.

But seriously: just click or Ctrl N and you are one step further.

A new note has popped up, named “Untitled“.

In the title bar above you see two arrows on the left. These are buttons to turn the page, as you know it from your web browser. Forward to the next note. Back to the last one.

In the middle of the title bar there is a text, combined from

• the title of your note
• the name of the current Vault (folder)
• and the Obsidian Version.

The display may change or be missing, depending on which theme you have activated.

By the way, for all screenshots in this article I have activated the theme “Blue Topaz “, in dark mode. You don’t have to like both. Then just bottom left, gear:

Settings > Appearance > Color Schemes [Manage].

and select another theme or switch to bright mode.

**Speaking of mode: **There is one thing you have to get used to!

If you never had to deal with a text editor before and edited your texts with MS-Word, Libre Office Writer, Google Office or the like, you only know one mode so far, and always the same one.

With an editor like Obsidian, you’re constantly switching between two views (actually there are three in Obsidian, but we’ll get to that later):

• Edit
• Read

You can switch with the mouse, top right, next to the “close” cross and the three-dot__menu for other actions.

In Edit mode you edit your text (aha!)

In reading mode your text is displayed in the finished version, English: rendered.

If you don’t like something about this rendering, you have to go back to

• go back to the edit mode.
• change what you do not like
• and switch back to “Presentation“.
• check if everything is good now
• if not …

Yes. It can go back and forth like that for a while.

The best thing to do is to remember the keyboard shortcut Ctrl E for this right now.

This is preset by default.

And that has already been the biggest “difficulty”, when dealing with Obsidian.

All other options are self-explanatory.

The best thing to do is to move the mouse over all the icons at the edge and just try out what happens!

Dealing with files

A big advantage of Obsidian is how “normally” the software handles your files, not to say transparently.

Unlike other programs, your data does not end up in any database or cloud. You always have to deal locally with ordinary text files. Even if the software fails for some reason (or doesn’t exist anymore), you keep full access to it. If necessary, you can use other word processing tools.

But Obsidian has a few peculiarities. That are worth to be considered before you start with Markdown.

Filename = note title = main heading

For Obsidian, every note is a file.

With the title of a note you define the file name.

And with the filename is at the same time fixed, under which designation you can set later links to this file – see further below, keyword: internal links.

I think it’s a good idea to make the note title also the main heading in the text, in Markdown format:

# Main heading

All other headings I set at least one level lower, in Markdown:

## First chapter
### First section
### ...
## Second ...

I do the same on pages for websites.

The rule that there should not be two “biggest” headlines on a page is not something I invented myself. Almost all SEOs adhere to this rule, thanks to Google.

Important: here in Obsidian this is a self-imposed rule!

Obsidian gives you complete freedom how to handle headings in the text, from # to ###### (in HTML from <h1> to <h6>).

Save file / save as

In Obsidian there is no command to save / save as a note file. Neither in the menus, nor as a keyboard shortcut (hotkey).

Obsidian saves your files automatically.

If you want to be sure that the current file is saved now, you can use

• Switch from Edit to Preview or Reading mode.
• or close the file.

Those are – probably – the two events that will definitely make Obsidian put the file on the disk again.

Search and retrieve files

The icon bar on the left, at the very top, opens on mouse click to the file explorer. By default with three tabs:

• Folder
• Search
• Stars

With folders in the foreground three more icons appear, for

• New note (file)
• New folder
• Sort file list

On the second tab you find all options for searching for files and folders. Also here an icon bar opens with further options.

The third tab in Obsidian File Explorer gives access to all files that you currently have starred. This works similar to the DeepL access in Windows. No matter how full your list of folders and files gets in your Obsidian Vault: You simply mark the very important ones with a star and thus secure DeepL access via the star menu in the File Explorer.

With these three options

• Folder
• Search and
• Stars

you can keep an overview of your Obsidian vault.

Much more is possible with Tags, Fields and especially Links. We will go into this further below.

Mode: Write, Read, Preview

I mentioned it briefly at the beginning: in Obsidian you actually switch between three views. Besides

• reading (Reading) and
• Source view (Source)

there is also a

• Live Preview (Live Preview)

This is a kind of middle ground between editing source text and viewing the result.

I was always confused by this in the beginning. Just the fact that already English uses different terms for it. The German translations don’t make it easier either!

I do not deny that all three views have their quality and justification. But it takes a while to get it right for your own way of working. And this could perhaps be accelerated if it were formulated more succinctly.

But! No matter!

Get used to it

You can find all 3 modes in the status bar at the bottom, right, as shown in the following image. Actually as a popup menu with the three options and an icon for each.

Don’t worry!

You’ll never get to see it like this again. I glued 4 screenshots together !
Now you know in any case: the Switch top right and the corresponding hotkey Ctrl E is only half the battle.

The other half reveals itself precisely in the Three-Dot-Menu, right next to it, as shown in the following screenshot (alternatively, these options are also available in the “Command Palette” with Ctrl P)

There are two switches!

• Toggle between Editor / Read mode (you already know this)
• and toggle between Live Preview / Source Code View.

And that’s not all. If you go to Settings > Options > Editor, both toggles appear again, this time as toggles between

• Editor View and Read View
• Live Preview and Source Code View

Well, is the confusion finally complete?

This much is certain: There are only three views in Obsidian.

1. Edit = source edit view (Source Edit)
2. Reading = Reading View (Reading)
3. Live–Preview (Live Preview)

With the settings you define:

• in which view notes appear that you create or open from the stock (defaultview: read or edit)
• in which view the editor opens when you switch from reading to editing (defaultmode: source or live)

Over time, you learn to appreciate the differences.

Only you will eventually realize, like me, to change between 3 modes you need at least 2 hotkeys.

Ctrl E alone does not do it!

V… where is the other one?

Useful keyboard shortcuts (hotkeys)

Not far from the Editor options you can also find the Hotkeys section in the Settings.

You can go through the whole, long list or try to find a shortcut using the search field, see the following screenshot.

Et voilà.

Here you will also find all hotkeys that are already preset. Here the already x-times mentioned toggle between Editor and Preview. You remember it?

Exactly. It’s

Ctrl E

And you guessed it: the other toggle also exists there, as shown in the following screenshot. Only they forgot to define a key shortcut for it.

But you can fix the “empty” very quickly yourself with the button to the right of it.

I have reserved **Ctrl Space** for this.

Now I can finally and ==hot==

• switch Read to Edit and back by Ctrl E
• switch Code-Edit to Live-Edit and back by Ctrl Space

Markdown standards in Obsidian

Before Obsidian, there were and besides Obsidian, of course, there are endless other text editors that can handle Markdown. Unfortunately, there are also different Markdown dialects.

I limit myself here only to Obsidian.

But you can see for yourself right away: Obsidian is not far from the “standard” at all. Where it differs, there are either good reasons. I’ll go into those. Or there is still hope that the developers will respond. With an update. One day.

At the end of the article you will find among other links

• to a Markdown Cheat Sheet
• and to the official Obsidian Markdown Reference.

Supported

Obsidian fully supports the following Markdown formats:

• Headings
• Paragraphs
• Line Breaks
• Bold
• Italic
• Strikethrough
• Highlight
• Horizontal Rules
• Blockquotes
• Ordered Lists
• Unordered Lists
• Task Lists
• Links
• Automatic URL Linking
• Disabling Automatic URL Linking
• Images
• Tables
• Footnotes
• Code
• Fenced Code Blocks
• Syntax Highlighting

A Cheat Sheet makes it really easier at the very beginning, until the Coding flies fluidly out of the keys. It’s not really like programming, but it feels like it sometimes.

In case you can’t think of anything spontaneously: what was that again with the blockquote? The solution starts with g and ends with oogle.

And!

Last but not least!

It is a fantastic idea, you create a new note, call it e.g. Markdown Cheat, and copy the “codes” into it, which are important for you.

Usually this works directly, with copy & paste or drag & drop, from the browser over into the obsidian note, and afterwards still a little trim, in the Markdown text.

A bit more luxurious is possible with special Markdown browser plugins. But this is a separate topic.

To prepare: Exactly! g…oogle helps!

Backticks on the German keyboard

However, I will briefly go into the matter of the backticks. At the beginning this can be more of a headache than necessary. But it is not that difficult.

On the German keyboard the decisive key is located between

• the one for “ß” (with Shift / Shift-key “?“)
• and the Backspace key

It is normally used for accents (emphasis characters). Therefore the keyboard is set so that you

• first type the accent (` or ‘ or ^)
• then the root character (usually a, e, i, o or u)
• to end up with e.g. à, é, î, ò or û

With the disadvantage that you always have to press two keys. You only get the accent character if you then press the space bar.

The ticks have nothing to do with the apostrophe ‘, which you probably got used to as simple quotation mark, because you don’t like the double ” or ran out of it.

In Markdown

• code snippets with single backticks and
• code blocks with triple backticks

see the following screenshots.

Source (source code) view:

And this is how it looks in live preview mode:

And finally the same note again in the Read View:

And what can I say. It comes even thicker

If you want to represent a code block as such, i.e. showing its backticks (and not being executed) even in preview and read mode, then you can wrap it again.

In fourfold backticks, as shown in the screenshot above.

Don’t ask me …

The good news:

You don’t have to add a space after each_ accented character. It’s enough if you enter it at the very end, as the last character.

Half supported

Let’s move on to the two features that Obsidian doesn’t quite implement as the Markdown creators envisioned.

Emojis

You can use this smiley_ and all others in Obsidian, just copy & paste. At the end of the article there is a link to the pretty complete table on GitHub (might be worth a note) What you can’t do in Obsidian: Use the text codes. For example, the smiley above has the code :smirk:

Attention: How emojis are displayed, is decided by the font. Technically they are _Unicode characters. And they look like this or like that in every font, or sometimes not at all.

Extra tip for Windows users:inside: In Windows 10 / 11 there is actually an Emoji menu, similar to what you are used to from your Android or Apple phone. Not quite as elegant to use, but still.

Try typing these two keys: Windows dot

HTML

As mentioned before, the Markdown standard basically provides that Markdown is compatible with HTML. That means you can insert a HTML snippet, switch from Edit to Preview or Reading, and the display changes to “nice”.

Obsidian restricts this for security reasons.

Above all, it blocks you from injecting JavaScript this way, which could do – you guessed it – anything! – to you.

The official Obsidian Markdown reference (link at end of article) doesn’t give any details about this. Doesn’t matter though.

The better way for your Java scripts is to use the Plugins Dataview and Templater (see below), or CustomJS..

So you can do really everything possible and Obsidian has no chance to protect you anymore

Not or better supported

The following four Markdown formats are actually not supported by Obsidian, as per the standard:

• Heading IDs (links to chapter headings).
• Definition Lists (say: dictionary lists)
• Subscript (character format: subscript)
• Superscript (character format: superscript)

Subscript, superscript and definitions

Why sub- and superscript, subscript and superscript character formats are not supported is – honestly – a mystery to me. Can even WordPress, as you see above

I feel similarly about Definition Lists.

Would be just another list format. But for some reason, the Obsidian developer:s refuse to implement that to this day. Only, admittedly! Just look around in the Plugin Lists for Dictionary, Dictionary etc. There should be a “workaround” for that, if needed.

However, Obsidian does support Heading IDs (Heading Links), in its own way, I think, much better than the Markdown standard was intended to do at some point.

Namely like this:

Internal links to headings in notes

If you feel like linking not only to the file name (note title), but directly to a heading contained there, then simply append it to the title of the link target, separated by a hash_, e.g.

[[Unbenannt 1#Überschrift 1]]

In the source code view you can type it directly like this.

Otherwise you can do it “interactively” as shown in the screenshot above, and Obsidian will kindly show you the way.

1. You open with a double square bracket.
2. obsidian shows you a list of files
3. You keep typing until you find what you are looking for.
4. then NO, you DO NOT CLICK on it!
5. You type the hash key #_
6. and Obsidian promptly shows you the content directory of the link target
7. you select the desired headline and
8. and NOW you may finally CLICK

This describes itself a bit complicated here.

If you go through this once, as shown in the screenshots …

It’s like riding a bike again

Obsidian Specials

Wikilinks

For external links, the standard format applies in Obsidian as everywhere in the Markdown world.

[title|alias](URL)

For example, a link to the Obsidian homepage:

[Obsidian|other text](`https://obsidian.md/`)

other text

For internal links Obsidian supports – apart from the Markdown standard – the so-called wikilinks:

“… it is sufficient to put the title of the page in double square brackets to link to the [[filename]] of another article or another section within an article. This format should be used wherever possible …” – Wikipedia

I have not researched who`s invented it. According to the name …

Anyway, I can only recommend from the bottom of my heart that you not only tolerate this deviation from the standard, but use it exactly like this, wherever you set internal links, in your Obsidian Vault.

There are people who have a counterargument. And that’s why you can disable the wikilinks option in the settings.

The argument is: safe is safe. Standard is standard. Safe is default. Grossly abbreviated:

The double square brackets are already exhausting enough. If one day in the distant future everything goes wrong, Obsidian no longer exists or is banned, and I have to change my entire notebook from wikilinks to standard links: well, then I`ll do it!

But until then I just put the filename of the link target in double square brackets, e.g.

[[Very important note]]

to the file of the same name in the Vault folder under

“d:\dropbox\my super-vault\critical\1a\Very important note.md"

Obsidian “knows” that already, remembers it reliably, too. Updates it even for me. And when typing it recognizes by auto-completion where I want to go.

Or rather everything by hand, file//... with %20 instead of spaces etc. ?

Frontmatter (YAML)

The abbreviation YAML once stood for Yet Another Markup Language. They have changed it for some reason.

Anyway: Obsidian can do YAML. But only at the very beginning of a note.

This is why the YAML block in Obsidian is called Front Matter. This block is used in Obsidian to manage metadata about a note (file).

By default, Obsidian currently supports (link at end of article)

• tags
• aliases
• cssclass
• publish

In markdown format, the first lines of a note will look something like this:

---
tags: tag1, tag2, tag3
aliases: alias1, alias2
cssclass: myclass
publish:
---

I will not go into the details of these four fields here.

Only point out: You can define any number and other fields here to make your note collection a kind of database.

Imagine, for example, that you want to create a movie database. Movies you have already seen, want to see soon, etc.

Then you create a note for each movie. And define for all movies a set of properties, say:

• Title: …
• Year of publication: …
• Actresses: …
• …

You guessed it.

Only double points for gendering don’t work here. Because of the YAML colon between field name and value we have to use a hyphen.

By the way: The YAML block with frontmatter metadata you normally only get to see in Edit mode (Edit). In Live Preview and Reading mode it remains hidden. Unless you don’t want that. You can find the appropriate setting in the Settings.

Yes, good. And how do you evaluate that?

Next Chapter.

For this you need a plugin!

Dataview plugin

I think if this fantastic plugin didn’t already exist, it would have to be reinvented at full speed.

Dataview is what makes Obsidian complete. Unlike Templater (see next chapter), there isn’t even an alternative.

What does Dataview do?

I’ll post a tutorial about that here soon.

In advance only so much:

• Dataview evaluates dynamically your notes
• Not the full text, but all data fields.
• A lot of fields are already included in Dataview (Implicit Fields)
• If you use frontmatter: Dataview can also evaluate YAML
• If you want to have own fields somewhere in the note text, Dataview is the right tool for that too (Inline Fields)

At the end of the article you will find a Link to Dataview Reference.

Dataview queries are noted in the Markdown text as code block.

You can formulate the query in two “flavors“.

• in DQL (Dataview Query Language) similar to SQL
• directly in JS (JavaScript)

Examples (quoted from the Dataview reference):

```dataview
TABLE file.name AS "File", rating AS "Rating" FROM #book
```

```dataviewjs
dv.taskList(dv.pages().file.tasks.where(t => !t.completed));
```

The first example shows how you can output a list with the simplified query language. Almost like English, in German:

• Output a table
• with the columns filename (file.name) and rating (rating)
• of all notes that are marked with the tag `#book

Apparently refers to a collection of notes about books.

In the second example, JavaScript is used to list _all unfinished tasks that can be found throughout the Vault.

That is all empty, unchecked Markdown checkboxes in all your notes, whether they occur anywhere individually or collected in checklists, e.g. of the sort

-[ ] Call Mom tomorrow

Does it say in your note against it (or you change it now like this)

-[x] Call Mom tomorrow

recognizes Dataview, you were good, this task (checkbox) is done and promptly! it disappears from the result list – dynamic – live!

How you can expand this, I leave for the moment to your imagination. Sorry. I must … next chapter!

Templates vs Templater

Another such ingenious plugin is Templater.

Not to be confused with Obsidian’s own internal plugin “Templates“.

With TemplateS I have – to be honest – hardly dealt.

But with TemplateR all the more intensive.

This plugin is also sufficient for several tutorials on its own.

Here only so much:

• The more you expand your note system to a knowledge platform, the more you will develop the need for forms and standards.
• Especially if you want to manage, query and evaluate your notes (or certain parts of them) in databases.

Let’s take the example movie database from above:

You don’t want to have to enter all the fields by hand every time you create a new movie, or copy and paste before you can fill in the fields.

Or: Example calendar sheets.

Let’s say you want to keep a diary. And you want to ask yourself the same questions every day about experiences, fulfilled goals and so on.

And sure. You want to automatically enter the date, what your name is, where you live …

Exactly. You need templates. You see !?

And here’s how it looks (an example, quoted from the templater reference, link at the end of the article).

---
creation date: <% tp.file.creation_date() %>
modification date: <% tp.file.last_modified_date("dddd Do MMMM YYYY HH:mm:ss") %>
---

<< [[<% tp.date.now("YYYY-MM-DD", -1) %>]] | [[<% tp.date.now("YYYY-MM-DD", 1) %>]] >>

# <% tp.file.title %>

<% tp.web.daily_quote() %>

Hossa!

Right away like this?

It’s just an example of what’s possible with Templater.

You must have recognized the Frontmatter block at the beginning immediately. Templater enters two fields there:

• creation date is the date when the note was created
• modification date is the date when it was last modified.

This has hooks and eyes and must be solved differently, in case of emergency. But that’s not what matters for this example.

The YAML block is followed by three single spaced lines.

• In the first two internal links are set, as wikilinks, in double square brackets. Templater invents the filenames between them based on the current date.
• A tag is subtracted for the left link. This should give the date of yesterday, in year-month-day format.
• For the right link, one day is added. Results in the date of tomorrow.
• In the second subtracted line Templater invents the headline for your new note and simply takes the filename for it (which you hopefully have already defined at that time
• And the third line is a joke in the margin. With it, Templater builds in a heavyweight quote of the day that it pulls from some database of significant quotes in world history (I forget where exactly

Granted.

The syntax, you can sometimes fall into a deep meditation. But that doesn’t have to be bad either. And: that should reassure you in any case.

There are so many great instructions and tutorials out there.

Often copy & paste is enough.

As long as you know what goes where to make it work.

What`s next?

When you start a tutorial like this, you don’t really know where you’ll end up.

It’s amazing every time: the more you write, the more you could add.

Of course, you can’t.

So I have to put you off again, to all the tutorials, tips and tricks that are still to come. Soon. Here.

But I’m not the only one you can get help from, thank God.

I hope, for today, you have taken one or the other with you, for your most elegant entry into the fascinating universe of Obsidian.

Good luck with it and above all: have fun with it!

Sources and links

Obsidian Markdown Reference | Markdown Guide

https://help.obsidian.md/Advanced+topics/YAML+front+matter

Markdown Cheat Sheet | Markdown Guide

Complete list of github markdown emoji markup · GitHub

Dataview

Introduction – Templater