Skip to content

Obsidian

Obsidian is a knowledge management system which runs on top of a local folder or 'vault; on your computer which can contain any number of plain text [[Markdown]] files or 'notes'. User's are encouraged to link notes within each vault. Their connections can then be visualised using the application's built in graph view.

The Obsidian desktop application is available for Windows, macOS and Linux operating systems, and is free for personal use. Additional features like syncing between devices and publishing notes online are paid services.

Personal Experience

I started using Obsidian as a way of quickly recording information in a simple format that can be linked together to establish relationships between different pieces of information. The graph visualisation plugin provided in the desktop application is ideal for quickly exploring those relationships. This is useful for building up a personal knowledge base that links helps establish conceptual links between different aspects of my technical and academic work. The use of Markdown means that the tool is simple, flexible, and works well with [[GitHub]]. Using GitHub Pages in combination with MKDocs provides a free alternative for publishing your Obsidian vault and collections of notes online (see obsidian-mkdocs below). The outcome is this website.

Tools & Software Integrations

  • obsidian-mkdocs by Jobin John - This is a template that gives you an automated way to publish your Obsidian notes on Github pages. Based on the MKDocs Material template by Martin Donath, this template provides selectable light and dark themes, a search bar, displays your Obsidian folder structure in the left sidebar, and displays the contents of a selected note on the right.
  • obsidiantools by Mark Farragher - A Python package for analysing Obsidian vaults. The package extracts structured metadata from Obsidian that can be analysed with Pandas or represented and analysed as a graph with NetworkX. A convenient demo has been provided as a Jupyter Notebook: obsidiantools-demo
  • Mermaid - Obsidian uses Mermaid.js to render diagrams and charts. It is a Javascript based diagramming and charting tool that uses Markdown-inspired text definitions to create and modify diagrams dynamically. NOTE: Be aware that Mermaid.js is currently an Material for MkDocs insider so it will work in Obsidian but is not yet available in online published MKDocs builds.
  • Prism - Obsidian uses Prism.js for syntax highlighting. This allows you highlight the syntax of code snippets according to the conventions of a particular programming language: Format your Notes: Code blocks This is achieved by providing the Prism code of a supported language: Prism: Supported Languages
  • Working Copy - Mobile Syncing for Obsidian can be achieved for FREE on iOS using GitHub with the free Git client Working Copy. Details for setting up the connection between the Obsidian app and working copy can be found here: Setting up iOS git-based syncing with mobile app(using Working Copy)
  • WATCH - IN DEVELOPMENT! obsidian-neo4j-stream by Emile van Krieken - This Obsidian plugin can stream your vault to a Neo4j server where it can be queried and analysed. Installation instructions can be found on the website for the associated Juggl graph visualisation plugin: Installing the Neo4j Stream Plugin

Obsidian provides a number of built-in core plugins which can be activated or deactivated within the desktop application. The Obsidian community also provides a large range of community plugins.

  • Calendar by Liam Cain. A simple Calendar view for visualizing and navigating between your daily notes.
  • DataView by Michael Brenan. Dataview is a community plugin that provides a live index and query engine over your Obsidian knowledge base. You can associate data with your markdown pages through annotation via [[YAML]] front matter or inline fields. You can then query this data to create lists of notes or create dynamic views. you can run arbitrary JavaScript against the dataview API. NOTE: The dynamic results of DataView queries do not render in GitHub Pages.
  • Graph View. This plugin provides an interactive visualisation of links between notes in your vault. This is ordinarily enabled by default.
  • Template. This plugin lets you quickly insert snippets of text into your current note. This needs to be enabled in Obsidian's Settings. The templates need to be stored in a specific folder (e.g. 'Templates') and this needs to be entered as the 'Template folder location' in Obsidian's Settings. Templates are written in markdown just as other notes are. The template can be added to an open note using Obsidian's Command Palette.
  • Tag pane. This plugin displays a list of tags in your notes and can be used for navigation. This needs to be enabled in Obsidian's Settings. One particular use is for adding #TODO tags to notes that need updating.
  • Tag Wrangler by PJ Eby. This community plugin adds a context menu to the tag pane which enables you to rename, merge, toggle and search tags. The search options enable you to 'require' or 'exclude' specific tags from search results. The main use of the plugin is tag management.

Resources

  • Obsidian Help - Official obsidian help documentation (also available in a separate Vault included with the Obsidian application).

Notes and Troubleshooting

Display images in GitHub Pages with MkDocs

MKDocs only builds what's in the 'docs' file. To ensure your images are included in your GitHub pages do the following: 1. Place your 'Attachments' folder inside your 'docs' folder in Obsidian. 2. Set the attachments folder as your default location for attachments in the Obsidian UI. Any media your paste into Obsidian will then be stored in that location. 3. When you build your site with obsidian-publish-mkdocs your images and links will be preserved so they display on your pages. 4. The Attachments folder is hidden from the site navigation so users won't have access to that folder.

NOTE: I'm not sure where the configuration that hides the attachments folder from the navigation is. It seems to work but worth flagging if that behaviour changes or breaks.

Embed YouTube and Vimeo Videos in Obsidian with iFrames

  1. Find the video you want to embed on YouTube or Vimeo.
  2. Click 'Share'.
  3. Copy the video 'Embed' code. The embed codes will appear as follows:

Google iFrame:

<iframe width="560" height="315" src="UNIQUE VIDEO EMBED URL HERE" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Vimeo iFrame:

<iframe src="UNIQUE VIDEO EMBED URL HERE" width="640" height="360" frameborder="0" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen></iframe>

The Vimeo embed iFrame also includes the video byline which can be kept or removed.

The video's unique embed URL inside the double quotes after the source tag src="UNIQUE VIDEO EMBED URL HERE". The embed URL will be different to the URL of the page the video appears on.

NOTE: The behaviour of the iFrames can be configured using parameters outlined in each service's documentation: - Google's documentation: https://developers.google.com/youtube/iframe_api_reference - Vimeo's documentation: https://vimeo.zendesk.com/hc/en-us/articles/360001494447-Player-parameters-overview

Mermaid.js

Add Mermaid Support to Obsidian Vaults Published with MKDocs

Add the following code to the mkdocs.yml configuration:

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

Source: https://squidfunk.github.io/mkdocs-material/reference/diagrams/

WARNING! Using this configuration at present will cause the website build to fail. Be aware that Mermaid.js is currently a Material for MkDocs insider feature so it will work in your local Obsidian vault but is not yet available for published MKDocs builds online.

Add Newline to Text in Mermaid Diagrams

Currently linebreaks are not fully supported but can be achieved by entering a closing Line Break <br/> HTML element.

graph TD
A(Line breaks<br />work in<br />rounded rec nodes)
B{Line breaks <br />work in<br />decision nodes}
C[Line breaks<br />work in<br /> rectangles]
D((Line breaks <br />work in <br />circles))
E>Line breaks <br />work in <br />flag nodes]

Source: https://github.com/mermaid-js/mermaid/issues/384

Scale Mermaid Diagrams to Fit Layout

Currently Mermaid diagrams can be cropped off the side of the page to the right. This can be resolved by placing a custom CSS snippet.

  1. Navigate to Settings > Appearance.
  2. Click 'Open Snippets folder'.
  3. Create and empty file custom-mermaid.css in the vault's snippet directory.
  4. Copy paste the following css into the file for horizontal fit:
.mermaid svg {
    max-width: 100%; 
    height: auto;
}

OR adapt the following for dynamic scaling:

svg[id^="m"][width][height][viewBox] {
    max-width: 95%;
    max-height: 95%;
} 

div.mermaid {
    margin-left: 0 !important;
    text-align: center; 
    resize:both; 
    overflow:auto; 
    margin-bottom: 2px; 
    position:relative; 
    max-height: 600px; 
    max-width: 100%; 
} 

div.mermaid::after { 
    content:''; 
    display:block; 
    width:10px; 
    height:10px; 
    background-color:blue; 
    position:absolute; 
    right:0; 
    bottom:0; 
}
  1. Save the updated css file.
  2. In the Obsidian appearance settings click 'reload snippets'.
  3. Click the toggle next to the listed snippet to enable it.

Source: https://forum.obsidian.md/t/ability-to-resize-and-align-mermaid-diagrams/7019/22

Transferring Settings Between Vaults

All of the settings, themes and plugins associated with an Obsidian vault are stored in the .obsidian folder. These can be transferred to a new vault by copying and pasting the folder across. Aftern copying the folder into a vault restart Obsidian to ensure the new settings take effect.

This can be useful if you are using Git to version control your vaults, but the vault settings have been included in your .gitignore file to avoid conflicts with mobile instances.