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:

• Vega charts plugin - this plugin allows for adding Vega Charts.

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

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.

Backlinks¶

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.

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.

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.

Links¶

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.

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.

Backlinks: