Obsidian Stats logoObsidian Stats

Negative Heading

by Ashan Devine
5
4
3
2
1
Score: 13/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

8
stars
469
downloads
1
forks
183
days
215
days
311
days
1
total PRs
1
open PRs
0
closed PRs
0
merged PRs
1
total issues
1
open issues
0
closed issues
25
commits

Latest Version

1.0.0
10 months ago

Changelog

First release (attempt 2)

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.
Linter
5 years ago by Victor Tao
An Obsidian plugin that formats and styles your notes with a focus on configurability and extensibility.
Zoom
5 years ago by Viacheslav Slinko
Number Headings
5 years ago by Kevin Albrecht
Automatically number headings in a document in Obsidian
Sort and Permute lines
2 months ago by Vinzent
Sort and Permute lines in whole file or selection.
Heading Shifter
4 years ago by kasahala
Easily Shift and Change markdown headings.
Lapel
4 years ago by Liam Cain
🤵 Dress up your editor. Obsidian plugin to show the heading level in the gutter.
Short Internal Links to Headings
4 years ago by Scott Moore
An Obsidian plugin to display short internal links.
Floating Headings
7 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.
Simple Tab Indent
a year ago by Thiago Frias
Edit mode switch
2 years ago by Mara-Li
Add a button in file header to switch between LP & Source while editing
Custom Theme Studio
a year 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.
Sticky Headings
2 years ago by Shen Shen
Insert Heading Link
5 years ago by Signynt
Add a Link to a Heading.
Heading Decorator
a year ago by dragonish
Implement displaying specific content around headings based on their levels.
Go To Heading
3 years ago by join
Quickly navigate between your document's headings in Obsidian
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.
Header Adjuster
2 years ago by Valentin Pelletier
Header level Reformat Plugin for Obsidian
Livecodes Playground
2 years ago by @gapmiss
Open-source client-side code editor plugin for Obsidian.md - powered by LiveCodes.io
Better Heading Hierarchy
a year ago by rogerfan48
a Obsidian plugin that add guide lines to make the hierarchy of Markdown headings more visually clear
Dynamic Text Concealer
3 years ago by Matt Cole Anderson
Obsidian.md Plugin to conceal or replace user configured text patterns in Live Preview and Read Mode.
YAML Table
a year ago by dainakai
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.
Dayframe
a month ago by Ganessh Kumar R P
🖼️ like a picture frame but for your daily notes.
Thecap cv generator
2 years ago by Thecap
Better Live Preview Image
a month ago by Dong Yang
Better Live Preview image editing for Obsidian
Reader Mode
a year ago by Dominik Mayer
Obsidian plugin that ensures notes are always opened in reader mode
Source Mode Styling
7 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.
Mode manager
2 years ago by dk949
Better management of reading/editing modes in obsidian
Adapt to Current View
a year ago by greetclammy
Obsidian plugin to set different accent colors for Reading view, Live Preview and Source view.
Format Automatically with Prettier
a year ago by Dylan Armstrong
Format with Prettier using built-in settings for Obsidian
Heading Helper
a year ago by Siddhartha Khuntia
Heading Toggler
2 years ago by Lord Turmoil
Toggle heading levels in Obsidian
JIRA links shortener
a year ago by Ruslans Platonovs
Obsidian JIRA links shortener plugin
Better Link Clicker
8 months ago by Eniverz
An Obsidian plugin that modifies the default link click event.
TableTune
22 days ago by niizhou
Tune your Obsidian tables: drag column/row borders to resize; sizes remembered per table; content-aware defaults; clean single-scrollbar reading view.
Table Resize
10 days ago by lishuai1993
调整obsidian中表格宽度的插件
Heading View
a month ago by 菅原ユリア
Sponsors