docsify-autoHeaders

---

---

Auto number headings

This plugin is designed to create heading numbers in your pages if you are creating a reference guide.

It stops you from having to manually number the heading, and then have to then trawl through every heading afterwards to change the numbering system again.

It allows you to either have all the headings in one page, or if you split them over many markdown documents then specify what the heading number it should be starting at.

Installation

Update index.html file

Assuming you have a working docsify framework set up, it is easy to use the plugin.

1. Add the following script tag to your index.html via either CDN or downloading it and using it locally:

   <!-- unpkg.com -->
   <script src="https://unpkg.com/@markbattistella/docsify-autoheaders@latest"></script>
   
   <!-- jsDelivr -->
   <script src="https://cdn.jsdelivr.net/npm/@markbattistella/docsify-autoheaders@latest"></script>
   
   <!-- locally -->
   <script src="docsify-autoheaders.min.js"></script>

2. In docsify setup configure the plugin (see configuration for setup):

<script>
window.$docsify = {
  autoHeaders: {
    separator: String,          // how numbers should be separated
    custom:    String,          // if `separator` is set to other then specify own here
    levels:    String | Object, // heading levels h[1-6]
    scope:     String,          // plugin search scope
    debug:     Boolean          // show console.log messages
  }
};
</script>

npm install

Or if you're using npm to manage your dependencies:

npm i @markbattistella/docsify-autoheaders

Configuration

There are some options available for the docsify-autoHeaders:

setting	options
separator	how the numbers are separated: decimal, dash, bracket, or other
custom	if separator is set to other then you can specify the custom styled separator here
levels	String: heading levels to target 1-6
	Object: start and finish for custom range
scope	the element to narrow it down to. #main is the default scope
debug	true or false if you want to see console.log info

Usage

At the top of your file add the following snippet:

@autoHeader:#

At the end of the identifier (marked with #), add the starting heading number. If you don't have a valid entry then it won't auto number.

It accepts only numbers.

You can have a starting header at 0 using:

@autoHeader:0

Customising individual numbers

You can also manually set the starting number of each of the levels by using the following format:

@autoheaders:3.5.6.6.1.12

##### New heading

Respectively starting the first level 6 heading (H6) at:

3.5.6.6.2.1 New heading

Start and finish range

You can also target specific heading levels for the numbering which works well if you want to skip H1.

<script>
window.$docsify = {
  autoHeaders: {
	separator: 'other',
	custom:    '--',
	levels:    {
	  start:  '2',
	  finish: '4'
	}
	scope:     '#main',
	debug:     false
  }
};
</script>

@autoheaders:1.2.3.4.5.6

# Level 1 heading

## Level 2 heading

### Level 3 heading

Level 1 heading

1-- Level 2 heading

1--2-- Level 3 heading

!> Note: though it skips H1, the numbering starts at the first integer from the @autoheaders:1.2.3.4.5.6 data. The above example should be read as @autoheaders:1.2.3

Contributing

1. Clone the repo:

   git clone https://github.com/markbattistella/docsify-autoHeaders.git

2. Create your feature branch:

   git checkout -b my-feature

3. Commit your changes:

   git commit -am 'Add some feature'

4. Push to the branch:

   git push origin my-new-feature

5. Submit the pull request