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 |

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

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" | "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.

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.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