Description

Customize Markdown heading appearance in Joplin with per-level styling controls for H1 through H6, while keeping note Markdown clean and unchanged.

Additional Information

Links:	Repository Homepage View source
Maintainers:	mh8
Version:	1.2.1
Minimum app version:	3.6
Downloads: This version:	0
Last updated:	N/A

Joplin Heading Control

Take control of your headings and make your notes easier to read with custom colors, font sizes, font weights, and spacing.

Before and after applying Joplin Heading Control:

Joplin Heading Control enhances Markdown headings in both the editor and viewer while keeping your note content clean and unchanged. Fine-tune heading colors, font size, font weight, and spacing for H1 through H6 to create a clearer visual hierarchy that fits your workflow.

Consistent styling in both editor and viewer:

Highlights

• Customize heading colors for H1 through H6
• Adjust font size and font weight per heading level
• Control spacing above and below headings
• Works in both editor and viewer
• Supports desktop and mobile
• Keeps note Markdown clean and unchanged

Technical Details

Joplin Heading Control is a small presentation-only plugin. It adds configurable colors, spacing and font size/weight to Markdown headings in both the Markdown editor and rendered viewer without injecting HTML into notes, rewriting headings, or changing stored Markdown.

Full Features List

• Configure a separate color for each Markdown heading level from H1 through H6.
• Configure per-heading space above and space below.
• Configure per-heading font sizes and weights.
• Apply heading colors in the Markdown editor and rendered Markdown viewer.
• Apply heading spacing in the Markdown editor and rendered Markdown viewer.
• Suppress additional top spacing when a heading is the first rendered content in a note.
• Persist configured heading settings across Joplin restarts.
• Preserve plain Markdown source exactly as written.
• Reject invalid color values and fall back safely to the corresponding default color.
• Support Joplin Desktop and Joplin Mobile.

Default colors

Heading	Default
H1	#7AA2F7
H2	#9ECE6A
H3	#E0AF68
H4	#BB9AF7
H5	#F87DFF
H6	#44D0C4

Only valid six-digit hexadecimal color values are accepted, using the format #RRGGBB.

Invalid values are ignored and the affected heading falls back to its default color.

Configuration

Desktop

Open Joplin Heading Control from either:

Ctrl+Shift+P (Command Palette) > Configure heading styles

or click the heading-control button in the top-right of the note toolbar.

Each heading level from H1 through H6 can be configured independently with:

• color
• font size
• font weight
• space above
• space below

Colors, font size, font weight, and spacing apply on both desktop and mobile.

Changes in the rendered viewer apply immediately after confirming the configuration dialog.

Important:

Markdown editor typography and spacing are currently read when the editor initializes, so restart Joplin if those changes do not appear immediately in the editor.

Mobile

On Joplin Mobile, open the plugin panels interface (button in the top toolbar) and select Joplin Heading Control, then choose Configure heading styles.

The configuration dialog supports the same H1 through H6 controls as desktop. The table can be swiped horizontally and zoomed if needed on smaller screens.

The configuration dialog currently opens behind the plugin panel, so close the plugin panel after selecting Configure heading styles to access it.

Mobile uses separately tuned default heading spacing, but all spacing values remain fully configurable.

Reset heading settings to defaults

On Joplin Desktop, open the Command Palette:

Ctrl+Shift+P

Run:

Reset heading settings to defaults

This restores all configured heading colors, spacing and font size/weight values to the plugin defaults.

Current refresh behavior

The reset command updates the stored settings immediately, but the currently displayed note may not visually refresh at once.

Rendered-view settings generally refresh when Joplin reapplies the plugin settings. Markdown editor spacing may require restarting Joplin before the refreshed values are applied.

Smoother live refresh of editor layout settings is planned for a future version.

Markdown remains untouched

The plugin is purely presentational.

A note such as:

# Project

## Hardware

### Networking

remains exactly that in the note source.

The plugin does not:

• inject HTML into notes;
• add custom Markdown syntax;
• rewrite headings;
• modify exported .md files;
• add formatting metadata to note content.

This keeps notes clean for sync, Git, export, other Markdown editors, and LLM-based workflows.

Desktop support

Joplin Heading Control supports Joplin Desktop with a minimum application version of Joplin 3.6.

Tested on Linux with Joplin 3.6.16.

Mobile support

The same plugin package also works on Joplin Mobile.

Current testing confirms heading styling in both:

• the Markdown editor;
• the rendered Markdown viewer.

Manual installation

Builds produce:

publish/io.gitlab.mh8.JoplinHeadingControl.jpl

On Joplin Desktop:

1. Open Tools > Options > Plugins.
2. Choose the option to install a plugin from file.
3. Select the .jpl package.
4. Restart Joplin if requested.

On Joplin Mobile, open the plugin settings and use the option to install a plugin from file.

Development

Repository:

https://gitlab.com/mh8/joplin-heading-control

Clone:

git clone git@gitlab.com:mh8/joplin-heading-control.git
cd joplin-heading-control
npm install

Build the plugin:

npm run dist

The generated plugin archive is written to:

publish/io.gitlab.mh8.JoplinHeadingControl.jpl

Technical approach

The plugin keeps editor and viewer styling separate:

• The Markdown editor uses a CodeMirror 6 content script and semantic heading tags.
• The rendered viewer uses a Markdown renderer content script.
• Joplin plugin settings provide persistent per-heading color and spacing values.
• Spacing is applied as viewer margins and CodeMirror line padding.
• Invalid color values are validated and replaced with safe defaults.

No note content is modified at any point.

Roadmap

Possible future additions remain intentionally limited to heading presentation.

Planned or considered:

• smoother live refresh of Markdown editor spacing and other future layout settings after configuration changes;
• optional underline or bottom-border controls;
• improved reset controls, potentially including per-heading reset actions;
• named heading-style presets if they can remain simple and portable;
• Refactor shared defaults into an API-independent module;
• Improve the mobile configuration flow, dismissing the plugin-panel launcher when opening the configuration dialog;

The project deliberately avoids becoming a general theme engine and is focused only on heading style.

Changelog

• 1.0.0 - Initial release with configurable H1-H6 colors in the Markdown editor and rendered viewer, desktop/mobile support, persistent settings, invalid-color fallback, and clean untouched Markdown.
• 1.1.0 - Adds per-heading desktop spacing controls for space above and below, preserves native mobile spacing, and suppresses extra top spacing for a heading at the start of rendered note content.
• 1.2.0 - Adds per-heading font size and font weight controls, extends configurable spacing to mobile with separately tuned defaults, introduces a compact custom configuration dialog with color pickers, adds desktop toolbar access and a mobile plugin-panel launcher, and improves H1 spacing below the editor underline.
• 1.2.1 - Fixed image links in README for Joplin Plugin marketplace.

Project scope

Joplin Heading Control exists to make Markdown hierarchy easier to scan while preserving Joplin's lightweight, Markdown-first workflow.

The core rule is simple:

Heading presentation may change. Markdown content must not.