Creating a theme

Inkdrop's interface is rendered using HTML and CSS. If you already have experience with web development, you're ready to go!

Inkdrop supports three types of themes: UI, Syntax and Preview:

• UI themes style elements such as the sidebar, the note list, drop-down lists, and the tool bar.
• Syntax themes style the note, gutter and other elements inside the editor view.
• Preview themes style the header, texts, code blocks and other elements inside the preview view.

Themes can be changed from Preferences which you can open by selecting the Inkdrop > Preferences on macOS or File > Settings on Windows and Linux, and clicking the Themes tab on the left hand navigation. Themes can be also installed with Inkdrop Plugin Manager.

Prerequisites

• Node.js (>= 24) - Used to install dependencies and run the theme development tools (npx dev-server, npx generate-palette).
• WSL on Windows - It's required to run the development server on Windows.

Getting Started

Themes are pretty straightforward but it's still helpful to be familiar with a few things before starting:

• CSS Variables are entities defined by CSS authors which contain specific values to be reused throughout a document.
• You may also want to review the concept of a package.json (as covered in Inkdrop package.json). This file is used to help distribute your theme to Inkdrop users.
• Your theme's package.json must contain a theme key with a value of ui, syntax or preview for Inkdrop to recognize and load it as a theme.
• You can find existing themes to install or fork in the Inkdrop themes registry.

Scaffolding a theme with ipm

The quickest way to start is the ipm CLI, which scaffolds a ready-to-edit theme into a new directory. Pick the --type that matches the theme you want to build:

# A syntax (editor) theme → creates ./motif-syntax
$ ipm init motif --type theme-syntax

# A UI (app chrome) theme → creates ./motif-dark-ui
$ ipm init motif-dark-ui --type theme-ui

# A preview (Markdown) theme → creates ./motif-preview
$ ipm init motif --type theme-preview

ipm appends the matching -syntax, -ui, or -preview suffix automatically when you leave it off. For UI themes it also sets themeAppearance from the name when it contains light or dark, and asks you otherwise. Run ipm init with no arguments to launch an interactive wizard that prompts for the name and type.

Each theme type is covered step by step below, starting from its ipm init command.

Enabling Development Mode

Development Mode enables the "Inspect Element" context menu in Inkdrop, which helps you build your themes easier. Select the menu Inkdrop > Preferences on macOS or File > Settings on Windows and Linux, click the General tab on the left hand navigation, and check the "Development Mode", then reload the app by pressing Alt+Cmd+Shift+R / Alt+Ctrl+R

Now you can use Chrome's Developer Tools. Right-click an HTML element you can to inspect its styles.

You can check how it's styled with themes in the Developer Tools like this:

Check out Google's extensive tutorial for a short introduction.

Installing the dev-tools plugin

There is a plugin called dev-tools that provides a set of useful tools for plugin development.

For theme development, it allows you to enable hot reloading of the current active themes. When you made any changes to your theme, it will reload the stylesheets automatically. So, you don't have to reload the entire app manually every time you made changes.

To start, select the menu Plugins → dev-tools → Start hot reloading themes. To stop, select the menu Plugins → dev-tools → Stop hot reloading themes.

Creating a Syntax Theme

Let's create your first syntax theme which is called motif-syntax. To create a syntax theme, do the following:

1. Run ipm init motif --type theme-syntax to scaffold the theme into ./motif-syntax (ipm adds the -syntax suffix for you).
2. Open a terminal in the motif-syntax directory.
3. Run ipm link --dev to symlink your repository to <USER_DATA>/inkdrop/dev/packages. You can find the user data directory as described on this page.
4. Reload Inkdrop using Alt+Cmd+Shift+R / Alt+Ctrl+R
5. Enable the theme via the "Syntax Theme" drop-down in the "Themes" tab of the Preferences
6. Enable hot reloading by selecting the menu Plugins → dev-tools → Start hot reloading themes

Now you are ready to make changes!

Open up styles/index.css. The scaffold ships the same complete, commented stylesheet as the stock default-light theme, so every variable and class you might customize is already there for reference. What Inkdrop actually reads is three groups of declarations:

• The editor chrome — --editor-* variables for the background, gutter, cursor, selection, tooltips, brackets, and more.
• The syntax tokens — Lezer highlight classes named .tok-* (.tok-keyword, .tok-string, .tok-comment, …), scoped under .cm-editor and .mde-preview .codeblock (the latter styles rendered preview code blocks).
• The Markdown-specific tokens — --md-* variables that style Markdown-specific syntax, such as fenced (triple-backtick) code blocks, inline code, highlight marks, and tables.

Set those to whatever colors you like — for example, reference @inkdropapp/css primitives such as hsl(var(--hsl-slate-800)) directly. The default theme also defines a base16-style palette at the top (--hsl-base00–--hsl-base0F and their --bd-* aliases) and points its other variables at it, which is a handy way to recolor everything from one place — but that's a convention specific to the default theme, not something your theme has to follow.

The editor runs on CodeMirror 6, so these --editor-* variables and .tok-* classes replace the old CodeMirror 5 .CodeMirror-* / .cm-* selectors. See Syntax themes in the migration guide for the full reference and the v5 → v6 selector mapping. After making changes, the app automatically reflects changes via the dev-tools hot-reloading.

Example syntax themes

• Solarized Light Syntax
• Solarized Dark Syntax

Creating a UI Theme

Let's create your first UI theme which is called motif-dark-ui. To create a UI theme, do the following:

1. Run ipm init motif-dark-ui --type theme-ui to scaffold the theme into ./motif-dark-ui. Because the name contains dark, ipm sets "themeAppearance": "dark" in package.json for you — when the name has neither light nor dark, it asks which one to use.
2. Open a terminal in the motif-dark-ui directory.
3. Run npm install to install dependencies.
4. Run ipm link --dev to symlink your repository to <USER_DATA>/inkdrop/dev/packages. You can find the user data directory as described on this page.
5. Reload Inkdrop using Alt+Cmd+Shift+R / Alt+Ctrl+R
6. Enable the theme via the "UI Theme" drop-down in the "Themes" tab of the Preferences
7. Start hot reloading by selecting the menu Plugins → dev-tools → Start hot reloading themes
8. Run npx dev-server to start the development server
9. Open the URL displayed in your console in a web browser
10. Edit your theme's styles/theme.css file to customize the theme
11. Run npx generate-palette to generate a palette.json file
12. Commit the generated palette.json file to your repository
13. Publish your theme

Customizing Theme Variables

Most of Inkdrop's UI elements can be customized with CSS variables. These variables let Inkdrop give meaningful names for styles of the UI components. For example, --note-list-bar-background variable styles the background of the note list bar. This approach saves you from handling CSS selector specificities, making your themes easier to maintain.

After creating a repository, there is an empty CSS file in styles/theme.css. You are going to add only the CSS variables that you want to change in this file.

For the full list of variables you can override, refer to the source CSS files in the @inkdropapp/css package, which the app loads before your theme:

• tokens.css — design tokens
• ui.css — the main file that defines CSS variables related to UI components
• status.css — note status colors (--note-status-*)
• tags.css — tag colors (--tag-*)
• task-progress.css — task progress view colors (--task-progress-view-*)

Running the Development Server

Let's check out what variables are available in Inkdrop. Inkdrop provides a helper tool to list all the CSS variables that are used in the app. Run the following command in the theme project root directory:

npx dev-server
#
#  VITE v5.4.9  ready in 710 ms
#
#  ➜  Local:   http://localhost:5173/
#  ➜  Network: use --host to expose
#  ➜  press h + enter to show help

The development server will start. Open the URL displayed in your console in a web browser.

There are three tabs in the tool:

• Variables: Lists all the CSS variables used in the app. As you can see, it includes not only colors but also border radii, sizes, font weights, and more. However, you don’t need to change every variable for your theme
• Color Tokens: Lists all the primitive color variables
  • Variables starting with --color- can be used as color values
  • Variables starting with --hsl- define HSL color parameters, such as 215deg 28% 17%, which are useful for adjusting opacity, for example, hsl(var(--hsl-gray-800 / 30%))
• Components: Previews some components with the current theme. The tool supports hot reloadig, so it will update colors as you modify the variables.

The full set of color tokens is also published in the @inkdropapp/css repository, where you can browse every available --color-* and --hsl-* variable.

Acrylic background support

The app supports acrylic background, which adds a frosted glass effect to the window background. It is currently supported on macOS and Windows 11+.

If this feature is enabled in the app, the body element will have the acrylic-window class name. So, you can add styles for the acrylic background like this:

:root:has(body.acrylic-window) {
  --page-background: transparent;
  --editor-background: hsl(192deg 100% 10% / 70%);
  --editor-drawer-background: hsl(var(--hsl-base04));
  --note-list-bar-background: hsl(var(--hsl-bg-muted-highlight) / 70%);
  --sidebar-background: hsl(var(--hsl-bg) / 70%);
  --inline-dropdown-menu-background: hsl(var(--hsl-base04));
}

It makes the background transparent, and increases transparency of the editor, note list bar, and sidebar.

On Windows, the window background opacity is lower than on macOS. So, you may want to adjust the styles by specifying the platform selector like so:

:root:has(body.acrylic-window.platform-win32) {
  --page-background: rgb(0 0 0 / 40%);
}

Generating palette.json

When you are ready to publish your theme, let's generate a palette.json file, which contains the variables in JSON format. This file is planned to be used for displaying a preview of your theme and also used for the mobile app in the future. Run the following command before publishing in the root theme project directory:

npx generate-palette

You can commit the generated palette.json file to your repository.

Example UI themes

• Solarized Light UI
• Solarized Dark UI

Creating a Preview Theme

Let's create your first theme which is called motif-preview. To create a preview theme, do the following:

1. Run ipm init motif --type theme-preview to scaffold the theme into ./motif-preview (ipm adds the -preview suffix for you).
2. Open a terminal in the motif-preview directory.
3. Run ipm link --dev to symlink your repository to <USER_DATA>/inkdrop/dev/packages. You can find the user data directory as described on this page.
4. Reload Inkdrop using Alt+Cmd+Shift+R / Alt+Ctrl+R
5. Enable the theme via the "Preview Theme" drop-down in the "Themes" tab of the Preferences
6. Start hot reloading by selecting the menu Plugins → dev-tools → Start hot reloading themes

Now you are ready to make changes!

After making changes, reload the app to reflected changes.

Example preview themes

• Solarized Light Preview
• Solarized Dark Preview

Publish your theme

Once you're happy with your theme and would like to share it with other Inkdrop users, it's time to publish it. 🎉

Follow the steps in the Publishing section of the Word Count example. Publishing a theme works exactly the same.