Demystifying Obsidian’s Outlining Superpowers
An Obsidian Guide for the Outliner
In this article, we will explore the outliner features of Obsidian.
There are two types of people: those who love Outliners and those who don't. Joking aside, I am a long-time user and lover of outlining as a method of taking notes.
However, ironically, I have for some time been extensively using Obsidian and Obsidian is not an outliner editor but a long-form markdown editor. Even so, you can achieve a comfortable “outliner-like” editing experience with Obsidian features and plugins.
Caveat: This approach still lacks many things for those with years of experience in using outliners. It is important to set expectations: we can have outliner like editing in Obsidian, but you will never be 100% satisfied, but you can be 60% to 80% satisfied.
From time to time I see a question about outlining, such as this one from Danny Hatcher:
Good question Danny!
In this article, I will explain what can be done with “native” Obsidian to accomplish outliner-like editing along with some plugins, which takes Obsidian outlining a few steps further.
This article will be especially useful to those coming to Obsidian from tools like Roam Research, Workflowy, Logseq, Remnote, and Tana.
Core Outlining Features of Obsidian
Obsidian has as a part of its core features a number of useful tools for outlining.
Smart indent lists
In Settings, under Editor options tab, enable the Smart indent lists option.
Once this feature is turned on, you can create a bulleted item in your notes and Obsidian will continue to add new bullets to the list as you go to new lines.
In other words, just like an outliner application, it allows you to create a list with bullets that expands as you create your notes and it also understands creating parent and child relationships by indenting a line with a Tab and unindenting a line with Shift-Tab.
This is a key aspect of outlining: creating structure through indentation levels of your notes.
This is easier to show than it is to explain, so please look at this next animated image closely:
As you can see, as I type I am able to create new bulleted items and indent and unindent them all from the keyboard. As I take notes, indenting and unindenting, the outline structure of my thoughts unfolds before me.
Under the hood, Obsidian is generating a standard markdown list. Here is what the plain-text file looks like:
What I like about Obsidian’s approach is that we get a standard markdown file that we can use in any text editor, but it's visually presented as an outline with bullets in Obsidian’s Live Preview.
Also as the image shows, these commands are invoked through the keyboard.
- Enter key for a new bullet
- Tab key for indented bullet (creating a parent-to-child node relationship)
- Shift-Tab key for unindenting (promoting a child to a parent node)
Expanding and Collapsing with “Folding”
Another important feature is Folding.
You might have to toggle this feature on. To do that, go into Obsidian’s Settings and view the Editor options tab and turn on Fold Heading and Fold Indent.
Those who love outlining appreciate the ability to expand and collapse the structure of the document’s outline. This allows us to hide away details from the notes we don’t currently want to see and focus on what we are editing. Outlines accomplish this by expanding or collapsing the structure of parent and child nodes.
Obsidian understands this concept as well. It might not be obvious on the surface, but Obsidian files have a lot of structure, just as outlines have structure. Structure in Obsidian is represented by Headings (Heading level 1, Heading level 2, etc) and bulleted item lists that can have parent-child relationships.
Folding allows us to expand and collapse these structures. Again, an animated image will make it clear. Notice how to fold in a bulleted list, using two different methods:
You’ll notice that we can fold the list at its parent levels using the command palette Toggle Fold on Current line command. This command can also be mapped to a keyboard hotkey to make it easy to frequently use.
Additionally, Obsidian puts little arrows next to the bullets that have children. These arrows allow us to fold and unfold the document's structure, revealing or hiding content we don’t want to see.
Note: some Obsidian Themes hide the fold/unfold arrows, so if you don’t see them, you will need to see if your theme supports these arrows.
This feature is even more valuable as your documents get to be long. The ability to hide away elements of the document we don't need to see keeps the mind focused.
Searching with Children Nodes
Obsidian also recognized children items in lists while doing searches. Notice the following image:
There is a lot going on here, but it's interesting. Let's break it down:
- When you type a search term in the search box, Obsidian finds all matching results. Obsidian recognizes the results found in lists.
- In the search pane, you can turn on “Show more content” which tells Obisidian to reveal more content related to search matches. In the case of this example, the children's items of the search match are shown.
- You can see as I toggle the indentation of the level of the outline in the document, the search results show more or less information as the children of the search match come in and out of scope for the search.
In review, the search pane understands lists and their parent/children relationships. You can increase the amount of content displayed in the search results from lists.
Transclusion
Transclusion is the ability to include information from one note in another note. While this is not directly related to outlining, it is an important feature that many outliners support.
Obsidian also supports transclusion. Obsidian allows us to transclude an entire note into another note or also to include just specific sections of a note into another note.
In the following image, I am transcluding a list item and its children's items.
Transclusion is a powerful tool for reusing information from your notes in other notes. This is especially helpful in writing projects where you have collected useful notes in various places in your vault and want to bring those thoughts together into another note.
For more information, check out these Obsidian help resources:
Extending Obsidian Outlining with Plugins
For many users, these core features just explained get us a lot closer to our outlining needs. However, with plugins, we can take this experience a few steps further.
Outliner Plugin
The Outliner Plugin was designed to enhance the outlining experience of Obsidian.
I think people get confused when using this plugin because they expect it to make Obsidian an Outliner. However, this plugin builds on the foundation of the core features already discussed in the previous section. Without these other features enabled in Obsidian settings, the outlining experience is incomplete even with the Outliner plugin.
The Outliner plugin introduces a number of useful features and I want to focus on four that I think are relevant to most outlining lovers.
First, please watch this brief video to see these features in action and then I will explain them in more detail.
Let's discuss these four points in detail.
Moving lists up and down
This feature when enabled allows you to move all the child nodes with their parent node as one group when the parent node is moved up and down in the list. Without this option, Obsidian just moves the current line.
Outlining assumes that the relationship between a parent node and its children will be maintained, and this feature gives us that behavior in Obsidian.
Sidebar: help feed the hungry writers. If you enjoy my writing, please give some thought to supporting my work. Follow me here on Medium, or better yet, sign up for a Medium membership and help support all your favorite writers using my referral link: https://bit.ly/o42-medium or if you literally want to feed me, buy me a coffee at: https://bit.ly/o42-kofi. Your support is appreciated!
Collapsing bar (or Vertical indentation line click action)
This is a feature I love. A vertical line appears along each bullet showing that it has children. Children can also have their own children, and this relationship is also shown with a vertical line.
As already mentioned, since this structure shows relationships, it is helpful to quickly collapse child nodes and even children of children.
The Outliner plugin, if enabled, allows you to click on that vertical line and all children will be collapsed to their parent level. When clicked again, they will collapse to the next parent level.
This gives us a way to step through the structure of the outline, one level at a time.
Styling
The plugin can do some tweaking to how bulleted lists are presented. It makes the bullets a little more refined. This is important to some people, but not really to me.
Stick the cursor to the content
This is a difficult one to explain. When editing an item in a bulleted list, it is easy to erase the dash at the beginning of a line.
- Bullet 1
- Bullet 2If you delete the dash, the list is broken. This plugin feature prevents the cursor from moving into the area where the dash is so you don’t accidentally drop yourself out of outlining mode by breaking the list.
Bonus: Ctrl/Cmd+A Select Current Item
I mentioned I would highlight four important features, but here is one more, and perhaps this is one of the best.
In most outliners, you edit the node (or block) one line at a time. You can often press Ctrl/Cmd+A on the keyboard for all the text to be selected on that node.
As can be seen in the next image, the default behavior of Obsidian when pressing this key combination is to select all the text of the entire document.
However, if you have turned on the select current item feature in this plugin, and you are editing a list, only the current item where your cursor is will be selected when pressing Ctrl/Cmd+a.
If you love outlining, you’ll know this is an important keystroke that most of us have committed to memory, and it's very confusing not to have it in Obsidian while outlining. This plugin saves the day!
Zoom Plugin
Let us go even a step further in making Obsidian a better tool for outlining.
There is another plugin called the Zoom plugin and it is made by the same developer as the Outliner plugin.
As mentioned earlier, one of our goals is to hide away parts of our outline that we don’t currently need to see, so that we can better focus our minds on the part of our outline that we are working on. The Folding feature helps us to collapse parts we don’t need to see.
But we can do better: enter the Zoom plugin.
The Zoom plugin understands that your document can be structured with the use of headings and bulleted lists. By using the command palette “Zoom: Zoom In” command, you can instruct the Zoom plugin to “zoom” into or show you just the contents of a document at a certain level and to hide the rest of the document above and below the area being zoomed.
This is illustrated in the next animated image:
When zoomed in on an area of your document, the breadcrumb trail of the structure is at the top of the window pane. This allows you to see the context of where you are editing your document. Also, you can click on various levels of the outline in the breadcrumbs to zoom to that level.
Even if a person doesn’t use the outlining features of Obsidian, the Zoom plugin is very useful and worth installing.
Obsidian is NOT an Outliner, but it is
As I mentioned earlier, the Obsidian outliner experience does not cover 100% of what we lovers of outliners desire. However, it is important to understand that Obsidian is not an outliner.
In fact, I don’t know if we will ever get native outlining features in Obsidian, as it is not really fundamental to the Obsidian team’s goals and design of the application. For me, this is ok. I am not disappointed. With all that I described so far in this article, we can do a lot of what is important to me.
What is missing to give Obsidian a better outlining experience? In my opinion, I would add two things:
- Better drag-and-drop support (drag a parent and all its children to a different point in the outline using the mouse)
- Better support for inline rendering of block references (right now Obsidian’s rendering of block references is inconsistent with other tools. Complaints welcome about this at this link 🤓.)
What would you change? Please share your thoughts in this article’s comment section of this article.
Final Advice
In conclusion, I appreciate that by combining core features and a few plugins, I can turn a long-form editor into a tool that gives me many of the benefits I miss from outlining tools.
But I have to admit, when I first started using Obsidian and the features discussed in this article, it was not a natural experience for me after years of working with outliners.
So my final advice to you is: you need to be patient and give yourself time to get accustomed to using these tools to accomplish outlining tasks. But I can promise that with a little time and effort, you will succeed and you will reap the benefits.
Thank you for reading this article. Please check out more of my work at https://tfthacker.com
