How to Use Markdown in Obsidian

Markdown in Obsidian is the foundation of everything the app does. Obsidian is a knowledge management tool that stores all your notes as plain .md files in a folder on your computer. There is no proprietary database, no cloud lock-in, and no special file format. Every note you create is a standard Markdown file that you can open in any text editor. This guide covers the Markdown features Obsidian supports, the extensions it adds, and how to organize your vault effectively.

What Obsidian is

Obsidian is a local-first note-taking application built on top of a folder of Markdown files, called a vault. Unlike Notion or Evernote, your data never has to leave your machine. The app reads your .md files, renders them with rich formatting, and adds powerful features like bidirectional linking, graph visualization, and a plugin ecosystem. But underneath, everything is just Markdown text files. If you stop using Obsidian tomorrow, your notes are still there, fully readable and portable.

Basic Markdown features in Obsidian

Obsidian supports standard Markdown syntax. Here is a quick reference of the most common elements:

All of these render live in Obsidian's reading view. In editing view, you see the raw Markdown syntax with subtle highlighting that makes it easy to read and write simultaneously.

Obsidian-specific Markdown extensions

Beyond standard Markdown, Obsidian adds several features that make it particularly powerful for building a knowledge base:

• —Internal links. Use [[Note Name]] to link to another note in your vault. Obsidian automatically tracks these connections and shows backlinks — every note that links to the current one. This is the core feature that turns a folder of files into a connected knowledge graph.
• —Tags. Add #tag-name anywhere in a note. Tags are searchable across your entire vault and can be nested, like #projects/active. Use them to categorize notes by topic, status, or type.
• —Callouts. Obsidian supports admonition-style callout blocks using a special blockquote syntax: > [!note], > [!warning], > [!tip]. These render as colored, collapsible boxes that are useful for highlighting important information.
• —Embedded notes. Use ![[Note Name]] (with the exclamation mark) to embed the full contents of another note inline. This is powerful for composing longer documents from smaller atomic notes, or for creating dashboards that pull in content from multiple sources.
• —YAML frontmatter. Add metadata to any note using a YAML block at the top of the file. Common fields include tags, aliases, date, and custom properties. Plugins like Dataview can query this metadata across your vault.

Organizing your vault

There is no single correct way to organize an Obsidian vault, but a few patterns have proven effective across the community:

• —Folders for broad categories. Use a small number of top-level folders like Projects, Areas, Resources, and Archive. This is loosely based on the PARA method. Avoid deeply nested folder hierarchies — they become rigid and hard to maintain.
• —Tags for cross-cutting topics. A note about a meeting can live in the Projects folder but still be tagged #meeting and #client/acme. Tags let you find notes by topic regardless of where they sit in your folder structure.
• —Maps of Content (MOCs). A MOC is a note that serves as a curated index for a topic. For example, a “Machine Learning MOC” note would contain links to all your notes about ML concepts, papers, projects, and tools. MOCs give you a navigable entry point into a topic without relying on search or the graph view.

Importing existing content into Obsidian

If you have existing documents — research papers, ebooks, meeting notes — trapped in PDF format, you can convert them to Markdown and add them directly to your vault. Use our PDF to Markdown converter to upload the PDF, review the converted output, and download the .md file. Then move the file into your vault folder. Obsidian will detect it automatically and you can start linking it to your other notes immediately.

This workflow is particularly useful for academic papers and technical reports. Convert the PDF, add it to a Resources folder, tag it with the relevant topics, and create links from your project notes. The paper becomes part of your knowledge graph instead of sitting unread in a downloads folder.

Useful plugins for Markdown workflows

Obsidian's community plugin ecosystem extends Markdown in powerful ways. Here are some of the most useful ones:

• —Dataview. Query your notes like a database. Write inline queries that pull data from YAML frontmatter across your vault. For example, list all notes tagged #book with a rating field, sorted by date. Dataview turns your vault into a lightweight personal database.
• —Templater. Create reusable note templates with dynamic content — dates, prompts, conditional logic. Useful for daily notes, meeting templates, project kickoff checklists, and any note type you create repeatedly.
• —Calendar. Adds a calendar view that integrates with your daily notes. Click any date to open or create that day's note. Pairs well with Templater for consistent daily note formatting.
• —Excalidraw. Embed hand-drawn diagrams directly in your Markdown notes. The diagrams are stored as files in your vault and can be linked and embedded like any other note.

Tips for a good Obsidian workflow

1. Write atomic notes. Each note should cover one idea or concept. This makes linking more useful because you can reference a specific idea rather than a long document.
2. Link generously. Whenever you mention a concept that has its own note, create a link. The more connections you make, the more useful the graph becomes over time.
3. Use daily notes. A daily note serves as an inbox for quick thoughts, tasks, and fleeting ideas. Review it periodically and move permanent content into dedicated notes.
4. Do not over-organize upfront. Start with a simple structure and let it evolve. Moving notes between folders is easy, and Obsidian updates all links automatically when you rename or move a file.
5. Back up your vault. Since your notes are local files, use Git, Syncthing, or a cloud folder to keep backups. Obsidian Sync is also an option if you want built-in cross-device sync.

Getting started

Obsidian is free for personal use and available on Windows, macOS, Linux, iOS, and Android. Download it, create a vault (which is just a folder), and start writing Markdown notes. If you have existing content in PDFs that you want to bring into your vault, convert them to Markdown first and drop the .md files into your vault folder. The combination of standard Markdown, internal linking, and a plugin ecosystem makes Obsidian one of the most flexible note-taking tools available.