Obsidian Stats logoObsidian Stats

Negative Heading

by Ashan Devine
5
4
3
2
1
Score: 35/100
Install Code

Description

The Negative Heading plugin turns lines that start with -# into compact muted headings, giving notes a lighter way to separate sections without using standard heading levels. It works across Reading View, Live Preview and Source Mode and keeps normal Markdown content such as bold text, italics and links inside the rendered line. A smart toggle command can add or remove the token on one line or across a selection, using majority based detection and preserving list markers when the syntax appears inside list items. The plugin also supports escape characters, ignores code and math blocks and uses theme aware colors with accessible heading semantics in Reading View.

Reviews

No reviews yet.

Stats

stars
240
downloads
0
forks
47
days
NaN
days
NaN
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
0
commits

Latest Version

Invalid date

Changelog

See all version on GitHub

README file from

Github

Negative Heading Plugin

An Obsidian plugin that renders Discord-style -# Heading lines as compact, muted headings in all view modes (Reading View, Live Preview, and Source Mode). The rendered block keeps normal Markdown content (bold, italics, links) while the -# marker is dimmed, creating lightweight subheadings perfect for organizing content without the visual weight of traditional headings.

Features

maindemo

  • All View Modes: Works seamlessly in Reading View, Live Preview, and Source Mode
  • Semantic Rendering: Reading View converts -# Heading into <div role="heading" aria-level="7"> for proper accessibility
  • CodeMirror Integration: Source mode and Live Preview use decorations for real-time syntax highlighting
  • Smart Toggle Command: Intelligently add or remove negative heading tokens based on majority detection
  • List Item Support: Works inside list items (- -# List heading)
  • Escape Character Support: Use \-# to prevent transformation (renders as literal -# text)
  • Context-Aware: Skips fenced code blocks, math blocks, and inline code for proper Markdown rendering
  • Theme Integration: Uses var(--text-muted) / var(--text-faint) with intelligent fallbacks to theme comment color or neutral gray
Some theme examples:

Usage

Manual Entry

  1. Type -# at the start of a line, follow with text.
  2. Switch to Reading View (or Live Preview) to see a compact heading that respects theme typography.
  3. In Source mode, the text is tinted to match muted text/comment colors so it remains identifiable.

Smart Toggle Command

The plugin provides a Smart toggle negative heading command that intelligently adds or removes the -# token based on context:

  • Single line: Place cursor on any line and run the command to toggle the token on/off.
  • Multiple lines: Select multiple lines and run the command. It will analyze the selection:
    • If majority are regular text → adds -# to all lines (SET operation)
    • If majority are already negative headings → removes -# from all lines (UNSET operation)
    • On a 50/50 tie → defaults to SET (add tokens)
  • List items: Preserves list markers (- , 1. , etc.) and inserts/removes the token after the marker.
  • Cursor preservation: Your cursor/selection position adjusts automatically after the transformation.

To use: Open the command palette (Ctrl/Cmd + P) and search for "Smart Toggle Negative Heading", or assign a hotkey in Settings → Hotkeys.

commandDemoWithHotkey

Examples:

  • Single line: Text here → -# Text here (and vice versa)
  • In lists: - Item text → - -# Item text (and vice versa)
  • Multiple lines: If you select 3 regular lines and 1 negative heading, all 4 become negative headings (majority rule)

Notes:

  • Only a single leading -# token is supported per block.
  • Syntax inside code fences and math blocks is ignored on purpose.
  • The smart toggle command skips empty lines and whitespace-only lines in multi-line selections.

Installation

From Obsidian Community Plugins (Recommended)

Note: Pending approval to the community plugins repository.

Once approved, you'll be able to install directly from Obsidian:

  1. Open Obsidian Settings
  2. Navigate to Community plugins and disable Safe Mode
  3. Click Browse and search for "Negative Heading"
  4. Click Install, then Enable

From source

npm install
npm run build

Copy the generated main.js, along with manifest.json and styles.css, into <vault>/.obsidian/plugins/negative-heading-plugin/.

Development

  • npm run dev - watch mode via esbuild.
  • npm run build - type-check plus production bundle.

Reload Obsidian after each build, or use the Reload app without saving hotkey in the developer tools.

Limitations

  • Only matches lines that begin with -# (at line start); indented lines are treated as plain text.
  • The plugin targets Obsidian v1.6+ where Live Preview and the current CodeMirror 6 API are available.
  • Single -# token per line (repeated markers are treated as plain text).
  • Nested Lists in Reader Mode: There is a known issue with rendering negative headings inside nested list items in Reader Mode. The styling may not apply correctly in deeply nested list structures. This is being investigated for a future update.

Testing

The plugin includes comprehensive automated testing:

npm test                    # Run all tests
npm run test:watch          # Watch mode
npm run test:visual         # Visual regression tests
npm run test:edge          # Edge case tests

Test Coverage:

  • 43 tests across 22 test files
  • 200+ edge case scenarios
  • Visual regression testing
  • Mode parity verification (Reading/Live Preview/Source)
  • Toggle command functionality
  • Escape character handling
  • List item behavior

Troubleshooting

Plugin doesn't appear in Reading View

  • Ensure you're using -# at the start of a line (not indented)
  • Check that the line isn't inside a code block or math block
  • Try reloading Obsidian

Styles look wrong

  • The plugin uses theme variables for colors
  • Check your theme supports --text-muted and --text-faint variables
  • Plugin provides fallbacks if variables aren't available

Toggle command isn't working

  • Ensure you have text selected or cursor on a line
  • Empty lines are skipped in multi-line selections
  • Check the command palette for "Smart toggle negative heading"

Escape characters not working

  • Use single backslash: \-# Text (not \\-# )
  • Verify you're using the correct syntax (backslash before the dash)

Architecture

This plugin uses a dual-pipeline architecture to support all Obsidian view modes:

  • Reader Mode Pipeline: DOM post-processing via registerMarkdownPostProcessor()
  • Edit Mode Pipeline: CodeMirror 6 decorations via registerEditorExtension()

For detailed architecture documentation, see ARCHITECTURE.md.

Contributing

Contributions are welcome! Please see AGENTS.md for development guidelines and project conventions.

Development Setup:

npm install
npm run dev    # Watch mode
npm test       # Run tests

Before submitting:

  • Ensure all tests pass (npm test)
  • Follow the coding conventions in AGENTS.md
  • Test in all three view modes (Reading View, Live Preview, Source Mode)
  • Test edge cases (lists, code blocks, escape characters)

License

This project is licensed under the GPL License. See LICENSE for details.

Changelog

1.0.0 (Initial Release)

  • Discord-style -# Heading syntax support
  • Smart Toggle Command with majority detection
  • Escape character support (\-# )
  • List item support
  • Works in all view modes
  • Comprehensive test suite

Similar Plugins

info
• Similar plugins are suggested based on the common tags between the plugins.
Insert Heading Link
4 years ago by Signynt
Add a Link to a Heading.
Lapel
4 years ago by Liam Cain
🤵 Dress up your editor. Obsidian plugin to show the heading level in the gutter.
Filename Emoji Remover
4 years ago by Yüksel Tolun
A simple plugin for the note taking app Obsidian that will rename your files to remove emojis in their names.
Heading Shifter
4 years ago by kasahala
Easily Shift and Change markdown headings.
Short Internal Links to Headings
3 years ago by Scott Moore
An Obsidian plugin to display short internal links.
Go To Heading
3 years ago by join
Quickly navigate between your document's headings in Obsidian
Orgmode (CM6)
2 years ago by Benoit Bazard
Orgmode plugin for Obsidian
Dynamic Text Concealer
2 years ago by Matt Cole Anderson
Obsidian.md Plugin to conceal or replace user configured text patterns in Live Preview and Read Mode.
Sticky Headings
2 years ago by Shen Shen
Livecodes Playground
2 years ago by @gapmiss
Open-source client-side code editor plugin for Obsidian.md - powered by LiveCodes.io
Headings in Explorer
2 years ago by Patrick Chiang
This Obsidian plugin makes headings first class concepts in the file explorer and consolidates navigation to a single panel.
Header Adjuster
2 years ago by Valentin Pelletier
Header level Reformat Plugin for Obsidian
Heading Toggler
2 years ago by Lord Turmoil
Toggle heading levels in Obsidian
Edit mode switch
2 years ago by Mara-Li
Add a button in file header to switch between LP & Source while editing
Zoom
5 years ago by Viacheslav Slinko
Linter
5 years ago by Victor Tao
An Obsidian plugin that formats and styles your notes with a focus on configurability and extensibility.
Number Headings
5 years ago by Kevin Albrecht
Automatically number headings in a document in Obsidian
Thecap cv generator
a year ago by Thecap
Mode manager
a year ago by dk949
Better management of reading/editing modes in obsidian
Heading Decorator
a year ago by dragonish
Implement displaying specific content around headings based on their levels.
Reader Mode
a year ago by Dominik Mayer
Obsidian plugin that ensures notes are always opened in reader mode
LawList: Custom List Styles
a year ago by Willem Schlieter
A plugin for custom list styles in Obsidian.md.
Format Automatically with Prettier
a year ago by Dylan Armstrong
Format with Prettier using built-in settings for Obsidian
JIRA links shortener
a year ago by Ruslans Platonovs
Obsidian JIRA links shortener plugin
Simple Tab Indent
a year ago by Thiago Frias
YAML Table
a year ago by dainakai
Better Heading Hierarchy
10 months ago by rogerfan48
a Obsidian plugin that add guide lines to make the hierarchy of Markdown headings more visually clear
Heading Helper
10 months ago by Siddhartha Khuntia
Custom Theme Studio
7 months ago by @gapmiss
An Obsidian.md plugin to create and tweak custom themes with live CSS editing, element styling, and instant previews. All without leaving Obsidian.
Adapt to Current View
7 months ago by greetclammy
Obsidian plugin to set different accent colors for Reading view, Live Preview and Source view.
Better Link Clicker
4 months ago by Eniverz
An Obsidian plugin that modifies the default link click event.
Floating Headings
3 months ago by k0src
Displays a floating, collapsible outline of a note's headings on the right side of the editor. Expands on hover, click to navigate.
Source Mode Styling
3 months ago by Chris Howard
Obsidian plugin. Provides a customisable raw look in source mode using a monospace font to clearly differentiate from Live Preview.
Sponsors