Obsidian

Obsidian
Initial release	10 March 2020
Operating System	Linux, macOS, Windows, iOS, Android
External links
Website	obsidian.md
GitHub	obsidianmd
Documentation	Obsidian Help

Obsidian is a proprietary note-taking application and Markdown editor. Notes are stored as regular files inside directories called vaults.

🟆︎

Tip: This package is unfree, and will require extra steps to install. You can read more about allowing unfree software in the Nixpkgs Manual.

Installation

NixOS

{
  nixpkgs.config.allowUnfree = true;

  environment.systemPackages = with pkgs; [
    obsidian
  ];
}

Home Manager

Home Manager can install Obsidian and manage settings for individual vaults.

{
  programs.obsidian = {
    enable = true;

    vaults.notes.target = "Documents/Obsidian";

    defaultSettings.app = {
      alwaysUpdateLinks = true;
      spellcheck = true;
    };
  };
}

The vault path is relative to the user's home directory. The example above manages ~/Documents/Obsidian.

The notes attribute is only an internal Home Manager name.

Note: Without a declared vault, Home Manager installs Obsidian but does not manage vault-specific settings, plugins or themes.

Core plugins

Core plugins are included with Obsidian and can be enabled declaratively:

{
  programs.obsidian.defaultSettings.corePlugins = [
    "backlink"
    "bookmarks"
    "daily-notes"
    "file-explorer"
    "global-search"
    "templates"
  ];
}

⚠︎

Warning: This list is exhaustive. Core plugins omitted from it are disabled. Leave the option unset to manage core plugins through Obsidian.

Plugin-specific settings can also be declared:

{
  programs.obsidian.defaultSettings.corePlugins = [
    {
      name = "daily-notes";
      settings = {
        folder = "Daily";
        format = "YYYY-MM-DD";
      };
    }
    {
      name = "templates";
      settings.folder = "Templates";
    }
  ];
}

Community plugins and themes

Home Manager supports packaged plugins and themes, but does not provide a package collection for them.

The third-party nix-obsidian-extensions flake provides packages from the official Obsidian registries.

⚠︎

Warning: This flake is not part of Nixpkgs, Home Manager, nix-community or the NixOS project.

Flake input

Add the input to flake.nix:

{
  inputs = {
    # ...

    obsidian-extensions = {
      url = "github:karaolidis/nix-obsidian-extensions";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  # ...
}

Overlay

Apply the overlay to the package set used by Home Manager:

{
  nixpkgs.overlays = [
    inputs.obsidian-extensions.overlays.default
  ];
}

This adds:

pkgs.obsidianPlugins
pkgs.obsidianThemes

When Home Manager is used as a NixOS module with home-manager.useGlobalPkgs = true, apply the overlay in the NixOS configuration.

Standalone Home Manager supports the same nixpkgs.overlays option.

Installing plugins and themes

{ pkgs, ... }:

{
  programs.obsidian = {
    enable = true;

    vaults.notes.target = "Documents/Obsidian";

    defaultSettings = {
      communityPlugins = with pkgs.obsidianPlugins; [
        dataview
        obsidian-git
        obsidian-importer
        vim-yank-highlight
      ];

      themes = with pkgs.obsidianThemes; [
        catppuccin
      ];
    };
  };
}

Plugin attributes use the IDs from the official Obsidian plugin registry. They do not always match the display names shown in Obsidian.

Available extensions can be listed with:

# Plugins
$ nix eval \
    --json \
    github:karaolidis/nix-obsidian-extensions#legacyPackages.x86_64-linux.obsidianPlugins \
    --apply builtins.attrNames

# Themes
$ nix eval \
    --json \
    github:karaolidis/nix-obsidian-extensions#legacyPackages.x86_64-linux.obsidianThemes \
    --apply builtins.attrNames

Plugin settings can be written to their data.json files:

{
  programs.obsidian.defaultSettings.communityPlugins = [
    {
      pkg = pkgs.obsidianPlugins.example-plugin;
      settings = {
        exampleOption = true;
      };
    }
  ];
}

Declarative and manual management

Declaratively managed plugins and themes are linked from the immutable Nix store.

Therefore:

they generally cannot be updated from Obsidian;
manual changes may be replaced on the next activation;
removing them from the Nix configuration removes them from the managed vault.

To manage plugins and themes manually, leave their options unset:

{
  programs.obsidian = {
    enable = true;

    vaults.notes.target = "Documents/Obsidian";

    defaultSettings = {
      communityPlugins = null;
      themes = null;
    };
  };
}

Both options are null by default.

Applying the configuration

# NixOS
$ sudo nixos-rebuild switch --flake .

# Standalone Home Manager
$ home-manager switch --flake .