How to Use YAML Front Matter in Obsidian

  • Post author:WunderTech
  • Post published:June 29, 2023
  • Post last modified:May 10, 2024
  • Post category:Obsidian
  • Reading time:13 mins read

Share what you're reading!

This tutorial will look at how to use YAML Front Matter in Obsidian. Adding Front Matter to your Obisidan notes will unlock a new way of tracking and retrieving important information. After configuring and adding YAML Front Matter, all of your notes will have hidden attributes that can be used for retrieval!

What is Metadata?

Now that we know that the YAML Front Matter in Obsidian is used to create Metadata, it’s important to understand exactly what Metadata is.

For the most part, Metadata is “data about data”. Metadata provides additional information about a particular set of data which allows you to understand, process, and organize it.

Using a text file as an example in the Windows operating system, the name, type, location, size, etc, are all stored as metadata about the file itself. It’s important to understand that this is not the content inside of the file, but rather data about the individual file itself.

text file metadata.

There are all kinds of different types of metadata based on the application, operating system, or file type you’re referencing, but in Obsidian, Metadata is structured as YAML Front Matter.

What is YAML Front Matter?

YAML Front Matter in Obsidian is a block of lines at the top of a Markdown file that contains metadata about the note. This metadata is specified in YAML (YAML Ain’t Markup Language) format and is delineated by two sets of triple-dashed lines.

test note with yaml front matter.

YAML Front Matter allows you to define certain variables and attributes about your note, providing additional information that can be used by Obsidian or plugins. In Obsidian, there are natively supported metadata fields (which we’ll take a look at below), but you can really use any type of metadata field that you’d like.

Creating YAML Front Matter in Obsidian

If you’re interested in using YAML Front Matter in Obsidian, it’s extremely straightforward to actually set it up. The power comes in utilizing it (which we’ll look at later in this article).

To create YAML Front Matter, at the top of any note, add three dashes at the top and the bottom. Everything in between those dashes will be considered metadata for this specific note.

title: Test Note
date: 2023-06-24
tags: ['tag1', 'tag2', 'tag3']
alias: Different Name

This is the main body of my note.
  • title defines the title of the note.
  • date defines the date the note was created or modified.
  • tags is a list of tags associated with the note.
  • alias provides an alternate name for the note.

Note that tags can be used in comma format (shown above) or list format (shown below).

title: Test Note
date: 2023-06-24
- option 1
- option 2
alias: Different Name

This is the main body of my note.

The code above is an example of YAML Front Matter, but to be entirely clear, there are a few very important notes that you must be aware of:

  • You must have YAML Front Matter at the very top of the note in Obsidian. If you don’t, it will not function properly.
  • You must have the “Metadata Name: Metadata Value” in that exact format. If you don’t format it properly, it won’t display properly.

If you’d like to have multiple values for an individual metadata field, you must use commas or hyphens (YAML code above). This will allow the metadata to hold multiple values.

test note with yaml front matter.

This example will be used throughout the rest of this article.

The specifics of what you include in your YAML Front Matter can be customized based on the actual relevant information of the note. For the most part, there may be common metadata fields, but the data will be different based on the individual note.

This means that the information above (title, date, tags, alias) can be entirely customized based on whatever information you’d like to track.

Natively Supported Metadata Tags

While Obsidian will allow you to use any metadata values you’d like, there are five different fields you can use as predefined metadata.

  • tag
  • tags
  • alias
  • aliases
  • cssclass

These fields will be recognized by Obsidian and will function differently than other metadata values that you decide to use. The best example is for tags, where you can specify the tag inside of the note itself using the # symbol (#Tag), or in the Front Matter using the tag (or tags) metadata value.

Search Results

When you actually configure YAML Front Matter, it’s accessible to the document, but also when you’re searching. Using the example above, you can find a document by its name (Test Note), or by its Alias (Different Name).

Title Search

test note search results.

Alias Search

retrieving a document by the alias.

Displaying or Hiding Front Matter

If you have YAML Front Matter added to a document, by default, the reading view will not display it. However, if you want it displayed, you can modify the Editor settings to show it.

displaying front matter.

Overall, there isn’t a right or wrong answer in terms of displaying or hiding it. For the most part, metadata looks cleaner when it’s hidden, but if you’d rather see it for each individual note (so that you always keep it up to date if necessary), this is the way to manage it.

Why Should You Use YAML Front Matter?

After looking at this example, you might be questioning why you should use YAML Front Matter in Obsidian. First, depending on how you’re structuring your notes, adding tags or aliases as Front Matter can give you an extremely powerful way of structuring hidden data.

While there are only a few set options for metadata that Obsidian natively supports (tag, tags, alias, aliases, cssclass), you can use any metadata value you’d like.

For example, if you’re taking notes for a specific application, it might be helpful to know which application the note is for. If you’re taking notes for a specific class, it might be helpful to know what class the note is for.

This is information that doesn’t necessarily have to be tracked in the note itself, but keeping track of it in the Front Matter is extremely powerful. This makes the overall note cleaner but also allows you to maintain important information that can be tracked if necessary.

yaml front matter in obsidian.

While we’re using a very broad example above, the metadata values that you use can be entirely different. In general, each note (or category of notes) can have different metadata.

For example, you can have a default set of metadata that is used across all notes or entirely unique metadata. The best way to describe this is by using the example above, where the metadata column class will determine which class this note is for. If you have multiple notes for different classes (English, History, Science, etc), you’ll be able to categorize your notes using the class metadata column.

This allows you to track standard metadata fields across all notes, but specific metadata values for different categories of notes. In general, the direction you take is entirely customizable and the benefit is that the data can be retrieved if required.

Dynamically Pulling Front Matter with Dataview

If you’re using the Dataview plugin, there’s almost no reason why you shouldn’t be using Front Matter. Dataview will allow you to dynamically pull information based on the metadata fields you’re using in your YAML Front Matter.

I have a full tutorial on Dataview that you should check out, but in summary, after metadata is defined, you can list it using a Dataview query.

where class = "English"
dataview retrieval.

Using the query above, you can easily create a dynamic list. The power of this comes when you have various types of notes all distinguished by Front Matter, where you utilize Dataview to dynamically display them.

dataview display.

Conclusion: How to Use YAML Front Matter in Obsidian

This tutorial looked at how to use YAML Front Matter in Obsidian. In general, Front Matter is not a requirement and isn’t something that you must use, but it is incredibly powerful. When you start to add Front Matter to your notes, you’re going to see that the data is easily retrieved and categorized.

This “new” form of categorization will allow you to easily access notes and will transform the way that you use Obsidian. It’s also something that doesn’t have a huge learning curve and is something you can implement in any note, quickly and easily. It also allows Obsidian to function similarly to Notion from a dynamic list perspective.

Thanks for checking out the tutorial on how to use YAML Front Matter in Obsidian. If you have any questions on how to use YAML Front Matter in Obsidian, please leave them in the comments!