Skip to content

Setting up Obsidian

Introduction

When you want to create some documentation, you need some tools that will help you with writing it. There are multiple ways of achieving it and one of them is to write documentation using flat files using Markdown syntax. This syntax is utilized not only by MkDocs, but also by other tools like Obsidian. In general, Obsidian is a note-taking app, but because it's a very flexible tool, it's quite often used for creating Personal Knowledge Management or a Second Brain.

Obsidian introduces some additional Markdown syntax options like callouts (equivalent to Markdown admonitions) and WikiLinks for creating internal links. Those internal links, in Obsidian, give you additional functionality of an automatic backlinks that just create a link to a document that mentions the document you are now reading. This way, you can have a better understanding of the relation in between 2 documents or topics that are described in them. If you want to know how the backlinks looks like, take a look at the bottom of this page.

Also, Obsidian has a huge variety of additional plugins, that allow to add some additional elements to the document, like charts, etc. Currently, the obsidian plugin, supports:

Support for more plugins is coming soon.

Creating Obsidian Vault

The most important thing if you want to use Obsidian as an IDE for creating a documentation, you have to create an Obsidian Vault inside a docs directory.

When the vault is created, inside docs directory, there will be created an .obsidian directory. This directory contains some Obsidian files with the app settings, additional files, etc.

.
├─ docs/
│  └─ .obsidian/
└─ mkdocs.yml

.obsdian directory

This directory can contain some crucial information, like paid Obsidian plugins credentials, etc. If you are using any git repository for storing your documentation, consider adding this directory into .gitignore to avoid potential security problems.

Do not remove this directory because you will lose your vault settings.

Obsidian templates

One of the benefits of using Obsidian, is the possibility to define and use templates for the whole document structure or parts of the document. To make use of the templates, you have create a template directory in docs directory and then set up the template plugin in Obsidian with the same template directory. By default, this directory name is set to _templates.

.
├─ docs/
│  ├─ .obsidian/
|  └─ _templates/
└─ mkdocs.yml

Configuration

To enable the built-in obsidian plugin, the following lines have to be added to mkdocs.yml file:

plugins:
  - pub-obsidian

General

plugins:
  - pub-obsidian:
    obsidian_dir: .obsidian
    templates_dir: _templates

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

obsidian_dir

Defines the name of an Obsidian directory, where all the setting files are stored.

templates_dir

Defines the name of an Obsidian directory, where all the note templates files are stored.

plugins:
  - pub-obsidian:
    backlinks:
      enabled: true

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

enabled

Control if backlinks are generated on the document web page.

Callouts

plugins:
  - pub-obsidian:
    callouts:
      enabled: true
      indentation: spaces

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

enabled

Control if callouts are generated on the document web page.

indentation

Defines if callout indentation whitespace type. Possible values: spaces (default) or tabs.

Comments

plugins:
  - pub-obsidian:
    comments:
      enabled: true
      inject_as_html: false

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

enabled

Control if comments are recognized on the document web page. If disabled, comments will be visible as a normal text.

indentation

Defines behavior of the comments:

  • true - comments will become an HTML comment, so it will not be visible on the generated document, but will be visible in document HTML code.

  • false (default) - comments will be completely removed and not visible either in generated document and document HTML code.

plugins:
  - pub-obsidian:
    links:
      wikilinks_enabled: true
      img_lazy: true

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

wikilinks_enabled

Control if WikiLinks format is supported.

img_lazy

Controls if all images should be lazy loaded. By default, this setting is enabled because it helps with SEO. However, you can disable this option and add set it up for each image separately.

Vega charts

plugins:
  - pub-obsidian:
    vega:
      enabled: true
      vega_schema: https://vega.github.io/schema/vega/v5.json
      vega_lite_schema: https://vega.github.io/schema/vega-lite/v5.json

Above you can find all possible settings with their default values. You don't have to provide them. Just use them if you want to change some settings. The description of the meaning of given setting, you can find below.

enabled

Controls if Vega charts are supported and will be rendered.

vega_schema

Link to JSON file with Vega scheme.

vega_lite_schema

Link to JSON file with Vega-lite scheme.