Lapel Obsidian Plugin

To set up the development environment, ensure you have Node.js (LTS recommended) and pnpm installed. Use pnpm exclusively to ensure dependency versions match the pnpm-lock.yaml file. Do not use npm or yarn.

pnpm install

Lapel provides the following configuration options in the Obsidian settings menu:

• Show before line numbers: When enabled, heading levels are displayed before the line numbers in the editor gutter. By default, they are displayed after the line numbers.
• Show in source mode: Enables or disables the visibility of heading levels when Obsidian is in Source Mode.

You can target specific heading levels for visual customization using CSS. Each heading marker uses the .cm-heading-marker class and a data-level attribute corresponding to the heading level (e.g., "1" for H1, "2" for H2). You can change the appearance by overriding the --heading-marker CSS variable.

Example: To change the H6 marker to a burger menu icon:

.cm-heading-marker[data-level="6"] {
  --heading-marker: "☰";
}

When calling headingMarkerPlugin, you can provide an options object of type HeadingMarkerPluginOpts to control visibility and gutter placement:

interface HeadingMarkerPluginOpts {
  showBeforeLineNumbers: boolean;
  showInSourceMode: boolean;
}

Lapel uses esbuild to bundle the plugin into a single main.js file. The following commands are available via pnpm:

• pnpm run lint: Runs ESLint over all .ts files. This must pass before any release.
• pnpm run dev: Runs esbuild in watch mode with inline sourcemaps. It outputs main.js to the repo root.
• pnpm run build: Runs lint first, then performs a minified production esbuild. It outputs a production main.js (without sourcemaps) to the repo root.

The LapelPlugin class is the main entrypoint for the Obsidian plugin. It manages the lifecycle of heading markers within the editor using CodeMirror extensions. It provides a mechanism to update settings dynamically, which triggers a workspace update to reflect changes in how heading markers are displayed (e.g., whether they appear before line numbers or in source mode).

// Note: As an Obsidian plugin, this is typically instantiated by the Obsidian app.
// Developers interacting with the plugin instance can use updateSettings to change behavior.

await plugin.updateSettings((oldSettings) => ({
  showBeforeLineNumbers: true,
  showInSourceMode: false
}));

The headingMarkerPlugin function creates a CodeMirror view plugin that adds heading level markers to the editor gutter. It provides a visual indicator of heading levels and allows users to change heading levels via a context menu when clicking the marker.

It returns an array containing the marker plugin and a gutter plugin. The gutter's priority (precedence) is determined by the showBeforeLineNumbers option.

import { headingMarkerPlugin } from './src/headingWidget';

const plugin = headingMarkerplugin({
  showBeforeLineNumbers: true,
  showInSourceMode: false
});

The updateSettings method allows for transactional updates to the plugin's configuration. It accepts a transformation function tx that receives the current LapelSettings and returns a Partial<LapelSettings>.

If the updated settings affect visual markers (specifically showBeforeLineNumbers or showInSourceMode), the plugin automatically regenerates the CodeMirror extension and calls this.app.workspace.updateOptions() to apply the changes immediately to the editor.

/**
 * @param tx A function that takes the current settings and returns the changes to apply.
 */
public async updateSettings(
    tx: (old: LapelSettings) => Partial<LapelSettings>
  ): Promise<void>

The LapelSettings interface defines the schema for the plugin's configuration. It contains the following boolean properties:

• showBeforeLineNumbers: Controls the gutter position of heading markers.
• showInSourceMode: Controls visibility in Obsidian's source mode.

export interface LapelSettings {
  showBeforeLineNumbers: boolean;
  showInSourceMode: boolean;
}