Docusaurus Numbered Headings

A simple Docusaurus plugin that automatically adds numbered headings (1., 1.1., 1.1.1., etc.) to h2, h3, and h4 elements in your documentation.

Features

• 🔢 Automatically numbers h2, h3, h4, and h5 headings
• 🎨 Clean CSS-based implementation using CSS counters
• ⚡ Zero JavaScript overhead - pure CSS solution
• 🌍 Support for multiple numbering conventions (ISO 2145 and USA Classic)
• 🔧 Easy to install and configure
• 🎛️ Optional configuration to disable if needed

Numbering conventions

Convention	Code	Structure Example	Common In	Region	Key Characteristics
Decimal (ISO 2145)	iso-2145	1, 1.1, 1.1.1	Technical, Scientific, Academic	Europe, Global	Clean hierarchy; easy to reference; used in Docusaurus, LaTeX, academic papers, theses; ISO standard
Classical Outline	usa-classic	I, A, 1, a	Academic essays, legal outlines	USA	Multilevel styles for papers; common in school instruction; Roman numerals + letters + numbers + lowercase letters
Spanish Forensic	spanish-forense	I, Primero.-, 1, a	Legal escritos, MASC, judicial	Spain	Upper-roman + written-out Spanish ordinals (Primero, Segundo…) at h3 + decimal + lowercase; idiomatic forense style

iso-2145

This style implements the international standard ISO 2145 for numbering sections in technical and scientific documents.

• Format: 1, 1.1, 1.1.1, etc.
• Each number level corresponds to a heading level (h2 → 1, h3 → 1.1, h4 → 1.1.1)
• Only decimal digits are used (no letters or Roman numerals)
• Clear, flat, hierarchical structure
• Widely used in academic, scientific, and technical documentation

Example:

## 2 Methods

### 2.1 Data Collection

#### 2.1.1 Survey Design

usa-classic

This style mimics the classical outline format commonly taught and used in the United States, especially in educational and legal contexts.

• Format: I, A, 1, a, etc. (Roman numerals, uppercase letters, digits, lowercase letters)
• Style progresses through different formats by depth
• h2 → Roman numeral (I, II, III)
• h3 → Capital letter (A, B, C)
• h4 → Arabic number (1, 2, 3)

Reflects traditional outline structures seen in essays, legal briefs, and academic writing in the US

Example:

## I. Introduction

### A. Background

#### 1. Early Work

spanish-forense

The dominant numbering convention for Spanish legal writings (escritos forenses): demandas, contestaciones, recursos, escritos de conclusiones, and pre-litigation submissions under the new Spanish MASC regime (Ley Orgánica 1/2025).

• Format: I, Primero.-, 1, a
• h2 → upper-roman (I., II., III.) — section headings like I.- HECHOS, II.- FUNDAMENTOS DE DERECHO
• h3 → written-out Spanish ordinals (Primero.-, Segundo.-, Tercero.-, …) — the single most distinctive marker of Spanish forensic style
• h4 → decimal (1., 2., 3.)
• h5 → lowercase letters (a., b., c.)

The Spanish ordinal counter supports Primero through Vigésimo (1–20); beyond that the counter falls back to decimal automatically. Suffix is .- (period-hyphen), the traditional Spanish forensic punctuation.

Example:

## Antecedentes

### Hechos del presente conflicto

### Antecedentes documentales

## Fundamentos de derecho

### Aplicación al caso

Rendered:

I. Antecedentes Primero.- Hechos del presente conflicto Segundo.- Antecedentes documentales II. Fundamentos de derecho Primero.- Aplicación al caso

Implementation uses CSS @counter-style, which requires Firefox (all versions), Chrome 91+, and Safari 17+.

Installation

npm install docusaurus-numbered-headings

or

yarn add docusaurus-numbered-headings

Usage

Add the plugin to your docusaurus.config.js:

module.exports = {
  // ... other config
  plugins: ["docusaurus-numbered-headings"],
  // ... rest of config
};

That's it! Your headings will now be automatically numbered.

Configuration

You can also pass options to the plugin:

module.exports = {
  // ... other config
  plugins: [
    [
      "docusaurus-numbered-headings",
      {
        enabled: true, // Set to false to disable the plugin
        convention: "iso-2145", // Choose numbering convention
      },
    ],
  ],
  // ... rest of config
};

Options

Option	Type	Default	Description
enabled	boolean	true	Whether to enable numbered headings
convention	"iso-2145" | "usa-classic" | "spanish-forense"	"iso-2145"	Numbering convention to use for the headings

Disabling Numbering on Specific Pages

You can disable numbered headings on specific pages using the class disable_numbered_headings.

<div class="disable_numbered_headings">
  <h2>Heading without numbering</h2>
  <p>This section will not have numbered headings.</p>
</div>

This implementation works because typically the reason for disabling numbered headings is to have a React component or a specific section that does not require automatic numbering. By wrapping the content in a div with the class disable_numbered_headings, the plugin will skip applying the numbering styles to that section.

Per-document control via frontmatter

Wire the bundled remarkFrontmatterToggle remark plugin into your docs preset:

// docusaurus.config.js
const { remarkFrontmatterToggle } = require("docusaurus-numbered-headings");

module.exports = {
  // ...
  presets: [
    [
      "classic",
      {
        docs: {
          remarkPlugins: [remarkFrontmatterToggle],
          // ...
        },
      },
    ],
  ],
};

Then in any MDX file, use the numbered_headings frontmatter key to control numbering on that page:

Frontmatter value	Effect
numbered_headings: false	Disable auto-numbering entirely on this page
numbered_headings: "iso-2145"	Force ISO 2145 (1, 1.1, 1.1.1) on this page
numbered_headings: "usa-classic"	Force USA Classic (I, A, 1, a) on this page
numbered_headings: "spanish-forense"	Force Spanish Forense (I, Primero.-, 1, a) on this page
numbered_headings: true	Explicit default (same as omitting the key)
(omitted)	Use the convention configured in docusaurus.config.js

Example — a formal document with manually-written Roman numerals that should not be auto-numbered:

---
title: My document
numbered_headings: false
---

## I. First section

Headings here are written by hand and will render exactly as written.

Example — an academic essay in a repo whose global convention is iso-2145, but which itself wants USA Classic outline numbering:

---
title: My essay
numbered_headings: usa-classic
---

## Introduction

### Background

Behind the scenes the remark plugin wraps the document body in <div className="..."> carrying one of:

• disable_numbered_headings (for false)
• numbered_headings_iso_2145 (for "iso-2145")
• numbered_headings_usa_classic (for "usa-classic")
• numbered_headings_spanish_forense (for "spanish-forense")

The CSS files shipped by the plugin define class-scoped rules for each override, which win by specificity over the global rules. The right-rail Table of Contents — which lives outside the wrapped document body — is scoped via :root:has(...), requiring a modern browser (Chrome 105+, Firefox 121+, Safari 15.4+).

Imports/exports and other MDX ESM nodes remain at the top level of the document. Requires Docusaurus 3+ (which exposes parsed frontmatter on file.data.frontMatter).

How it works

This plugin injects CSS that uses CSS counters to automatically number your headings based on the selected convention:

ISO 2145 Convention (default)

• H2 headings get numbers like: 1., 2., 3.
• H3 headings get numbers like: 1.1., 1.2., 2.1.
• H4 headings get numbers like: 1.1.1., 1.1.2., 1.2.1.
• H5 headings get numbers like: 1.1.1.1., 1.1.1.2., 1.1.2.1.

USA Classic Convention

• H2 headings get Roman numerals: I., II., III.
• H3 headings get uppercase letters: A., B., C.
• H4 headings get decimal numbers: 1., 2., 3.
• H5 headings get lowercase letters: a., b., c.

The numbering resets appropriately when moving between different heading levels.

Styling

If you want to customize the appearance, you can override the CSS in your custom stylesheet:

h2::before,
h3::before,
h4::before {
  color: #your-color;
  font-weight: bold;
  /* your custom styles */
}

Compatibility

• ✅ Docusaurus v2.x
• ✅ Docusaurus v3.x
• ✅ Works with Markdown and MDX files
• ✅ Compatible with all Docusaurus themes

License

MIT

Contributing

Issues and pull requests are welcome! Please check the GitHub repository for more information.

Changelog

1.6.0

• Added remarkFrontmatterToggle remark plugin: per-document control via the numbered_headings frontmatter key
  • false → disable auto-numbering on the page
  • "iso-2145" → force ISO 2145 on the page (override global)
  • "usa-classic" → force USA Classic on the page (override global)
  • "spanish-forense" → force Spanish Forense on the page (override global)
• New spanish-forense convention: upper-roman at h2 + written-out Spanish ordinals at h3 (Primero.-, Segundo.-, Tercero.-, …) + decimal at h4 + lowercase letters at h5. The idiomatic numbering for Spanish legal escritos (demandas, contestaciones, MASC submissions under Ley Orgánica 1/2025). Uses CSS @counter-style.
• New class-scoped override stylesheets (iso-2145-override.css, usa-classic-override.css, spanish-forense-override.css) loaded alongside the existing global convention
• TOC scoping via :root:has(...) so the right-rail Table of Contents respects the per-doc setting (requires modern browsers)

1.5.0

• Added support to disable numbered headings
• Enhanced documentation for disabling numbering

1.4.0

• Added support for table of contents (ToC) numbering
• Improved CSS for better compatibility with various themes

1.3.0

• Remove margin-right from h2-h5 pseudo-elements
• Clean up styles across all conventions
• Added comprehensive CI/CD workflows for automated deployment

1.2.0

• Enhanced package configuration and security
• Added comprehensive .npmignore for optimized package size
• Added security policy (SECURITY.md)
• Improved npm discoverability with additional keywords
• Added Node.js engine requirements (>=16.0.0)
• Package size optimized to 5.2kB compressed

1.1.0

• Added support for multiple numbering conventions
• Added iso-2145 convention (decimal numbering: 1, 1.1, 1.1.1)
• Added usa-classic convention (Roman numerals, letters, numbers: I, A, 1, a)
• Extended numbering support to h5 elements
• Improved configuration options

1.0.0

• Initial release
• Basic numbered headings for h2, h3, h4
• Plugin configuration options