obsidian: (RFC) add module

[karaolidis]

Motivation

Currently, Obsidian lacks first-class Nix integration (#6321). Users have to manually install the app and manage settings, plugins, and themes outside of Nix. This module aims to make Obsidian declarative by handling vaults, themes, and plugin management via Home-Manager.

Overview

This module provides:

• Vault Management - Create and configure vaults declaratively.
• Plugin Management - Install both core and community plugins with settings.
• Theme & Snippets Support - Declarative theme selection and CSS snippets.
• Hotkey Customization - Keybindings in Nix.
• extraFiles - Symlinking arbitrary files in a vault.

Example Configuration

home-manager.users.${user} = {
  programs.obsidian = {
    enable = true;

    vaults."Documents/Obsidian/master".enable = true;

    defaultSettings = {
      app = {
        defaultViewMode = "preview";
        livePreview = false;
        readableLineLength = true;
        showLineNumber = true;
        tabSize = 2;
        ...
      };

      corePlugins = [
        "bookmarks"
        {
          name = "canvas";
          options = {
            newFileLocation = "folder";
            newFileFolderPath = "Inbox";
            defaultWheelBehavior = "zoom";
          };
        }
        "canvas"
        ...
      ];

      communityPlugins = [
        {
          pkg = pkgs.callPackage ./config/plugins/custom-sort { };
          options = {
            suspended = false;
            statusBarEntryEnabled = false;
            notificationsEnabled = false;
            customSortContextSubmenu = false;
            bookmarksGroupToConsumeAsOrderingReference = "Sort";
            bookmarksContextMenus = false;
          };
        }
        {
          pkg = pkgs.callPackage ./config/plugins/dataview { };
          options = {
            enableDataviewJs = true;
            enableInlineDataviewJs = true;
            warnOnEmptyResult = false;
            defaultDateFormat = "dd/MM/yyyy";
            defaultDateTimeFormat = "HH:mm - dd/MM/yyyy";
          };
        }
        (pkgs.callPackage ./config/plugins/style-settings { })
        ...
      ];

      cssSnippets = [ ./config/snippets/file-explorer-separators.css ];

      themes = [ (pkgs.callPackage ./config/themes/minimal { }) ];

      hotkeys = {
        "command-palette:open" = [ { key = "F1"; } ];
        "app:open-help" = [ ];
        "editor:swap-line-down" = [
          {
            modifiers = [ "Alt" ];
            key = "ArrowDown";
          }
        ];
        ...
      };
    };
  };
};

Open Questions

• Plugins and themes follow a fetch-from-source model and are version-dependent. Should they be included in Nixpkgs, NUR, or somewhere else?
• Should default settings be deeply merged or overridden? Should we even include defaultSettings?
• Should we keep the option names options and settings, or is something else more appropriate, e.g. config?

Checklist

• Change is backwards compatible.

• Code formatted with ./format.

• Code tested through nix-shell --pure tests -A run.all
  or nix build --reference-lock-file flake.lock ./tests#test-all using Flakes.

• Test cases updated/added. See example.

• Commit messages are formatted

• Added myself as module maintainer. See example.

Maintainer CC

@rycee

[karaolidis]

For reference, here is an example plugin package:

{ pkgs, ... }:
pkgs.stdenv.mkDerivation rec {
  pname = "obsidian.plugins.tasks";
  version = "7.15.0";

  src = pkgs.fetchFromGitHub {
    owner = "obsidian-tasks-group";
    repo = "obsidian-tasks";
    rev = version;
    hash = "sha256-BF9ye4ocE6vZh+ChkmuLkQpNWtH425EX0EHQs+wbTZc=";
  };

  offlineCache = pkgs.fetchYarnDeps {
    yarnLock = src + "/yarn.lock";
    hash = "sha256-Tf1K048Ox+hImIfrdBWQHsiDe+3FGUQLFBcf/Bbbo1U=";
  };

  nativeBuildInputs = with pkgs; [
    nodejs
    yarnConfigHook
    yarnBuildHook
    npmHooks.npmInstallHook
  ];

  installPhase = ''
    mkdir -p $out
    cp ./manifest.json $out/manifest.json
    cp ./main.js $out/main.js
    cp ./styles.css $out/styles.css
  '';
}