@markbattistella/docsify-autoheaders 5.0.0 → 5.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/CHANGELOG.md +11 -2
  2. package/README.md +55 -116
  3. package/dist/docsify-auto-headers.js +610 -576
  4. package/dist/docsify-auto-headers.min.js +1 -2
  5. package/package.json +10 -10
package/CHANGELOG.md CHANGED
@@ -1,5 +1,14 @@
1
+ ## 5.1.0 - 2025-09-04
1
2
 
2
- ## 5.0.0 - Tue Jun 11 2024
3
+ - If you are using Front Matter you can use `autoHeader: xx` in there instead of needing the signifier to be the first line
4
+
5
+ ## 5.0.1 - 2024-06-11
6
+
7
+ ### Fixed
8
+
9
+ - Documentation fixes.
10
+
11
+ ## 5.0.0 - 2024-06-11
3
12
 
4
13
  ### Breaking Changes
5
14
 
@@ -9,4 +18,4 @@
9
18
  - Allows numbering in sidebar and main body
10
19
  - Better handling of debugging
11
20
  - Numbering can use letters and not just numbers
12
- - Many more fatures and cleanups
21
+ - Many more features and cleanups
package/README.md CHANGED
@@ -1,33 +1,30 @@
1
1
  <div align="center">
2
2
 
3
- # docsify-auto-headers
4
-
5
- ![Github2npm](https://github.com/markbattistella/docsify-autoHeaders/workflows/gh2npm/badge.svg?event=registry_package) ![npm (scoped)](https://img.shields.io/npm/v/@markbattistella/docsify-autoheaders) ![GitHub](https://img.shields.io/github/license/markbattistella/docsify-autoheaders) ![npm bundle size (scoped)](https://img.shields.io/bundlephobia/minzip/@markbattistella/docsify-autoheaders)
6
-
7
- ---
8
-
9
- [![](https://img.shields.io/badge/%20-@markbattistella-blue?logo=paypal&style=for-the-badge)](https://www.paypal.me/markbattistella/6AUD)
10
- [![](https://img.shields.io/badge/%20-buymeacoffee-black?logo=buy-me-a-coffee&style=for-the-badge)](https://www.buymeacoffee.com/markbattistella)
3
+ # docsify.js auto-headers
11
4
 
12
5
  </div>
13
6
 
14
- ---
15
-
16
- # Auto number headings
7
+ This plugin enhances your Docsify documentation by automatically generating numbered headers for your markdown files. It allows you to configure the header levels, numbering format, and inclusion in the sidebar. By utilising this plugin, you can easily manage and navigate through your documentation headers, ensuring consistency and improved readability.
17
8
 
18
- This plugin is designed to create heading numbers in your pages if you are creating a reference guide.
9
+ ## Demo pages
19
10
 
20
- 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.
21
-
22
- 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.
11
+ | Page link | Description |
12
+ |-|-|
13
+ | [![](https://img.shields.io/badge/page_1--blue?style=for-the-badge)](pages/_page1) | The `autoHeader` of this page is: `@autoHeader:1`.<br>Assuming the original configuration is used, the splitter is `.` and the levels are `H1`-`H6`. |
14
+ | [![](https://img.shields.io/badge/page_2--blue?style=for-the-badge)](pages/_page2) | The `autoHeader` of this page is: `<!-- autoHeader:11.22.33.44.55.66 -->`.<br>Assuming the original configuration is used, the splitter is `.` and the levels are `H1`-`H6`. |
15
+ | [![](https://img.shields.io/badge/page_3--blue?style=for-the-badge)](pages/_page3) | The `autoHeader` of this page is: `@autoHeader:`.<br>Assuming the original configuration is used, the splitter is `.` and the levels are `H1`-`H6`. |
16
+ | [![](https://img.shields.io/badge/page_4--blue?style=for-the-badge)](pages/_page4) | The `autoHeader` of this page is: `<!-- autoHeader:Z.Y -->`.<br>Assuming the original configuration is used, the splitter is `.` and the levels are `H1`-`H6`. |
17
+ | [![](https://img.shields.io/badge/page_5--blue?style=for-the-badge)](pages/_page5) | The `autoHeader` of this page is: `<!-- autoHeader:1-2-3 -->`.<br>Assuming the original configuration is used, the splitter is `.` and the levels are `H1`-`H6`. |
23
18
 
24
19
  ## Installation
25
20
 
21
+ !> Note: There are breaking changes in the configuration from `v4.x` to `v5.x`. Please take the time to read all the documentation before upgrading
22
+
26
23
  ### Update `index.html` file
27
24
 
28
25
  Assuming you have a working [docsify](https://docsify.js.org/) framework set up, it is easy to use the plugin.
29
26
 
30
- 1. Add the following script tag to your `index.html` via either CDN or downloading it and using it locally:
27
+ 1. Add one of the following script tags to your `index.html` via either CDN or downloading it and using it locally:
31
28
 
32
29
  ```html
33
30
  <!-- unpkg.com -->
@@ -40,134 +37,76 @@ Assuming you have a working [docsify](https://docsify.js.org/) framework set up,
40
37
  <script src="docsify-autoheaders.min.js"></script>
41
38
  ```
42
39
 
43
- 1. In docsify setup configure the plugin (see [configuration](#configuration) for setup):
40
+ 1. In docsify setup, configure the plugin:
44
41
 
45
- ```js
46
- <script>
47
- window.$docsify = {
48
- autoHeaders: {
49
- separator: String, // how numbers should be separated
50
- custom: String, // if `separator` is set to other then specify own here
51
- levels: String | Object, // heading levels h[1-6]
52
- scope: String, // plugin search scope
53
- debug: Boolean // show console.log messages
54
- }
55
- };
56
- </script>
57
- ```
42
+ ```js
43
+ <script>
44
+ window.$docsify = {
45
+ autoHeaders: {
58
46
 
59
- ### npm install
47
+ // Separator for header numbering (e.g., '.', '-', ')')
48
+ separator: '.',
60
49
 
61
- Or if you're using `npm` to manage your dependencies:
50
+ // Boolean indicating if headers should be added to the sidebar
51
+ sidebar: false,
62
52
 
63
- ```sh
64
- npm i @markbattistella/docsify-autoheaders
65
- ```
53
+ // Number of header levels to include (1 to 6) or an object with start and finish properties
54
+ levels: 6,
55
+ // levels: { start: 1, finish: 6 }
66
56
 
67
- ### Configuration
57
+ // Boolean to enable or disable debug messages
58
+ debug: false
59
+ }
60
+ };
61
+ </script>
62
+ ```
68
63
 
69
- There are some options available for the `docsify-autoHeaders`:
64
+ ## Configuration
70
65
 
71
- | setting | options |
72
- |-----------|-----------------------------------------------------------------|
73
- | separator | how the numbers are separated: `decimal`, `dash`, `bracket`, or `other` |
74
- | custom | if `separator` is set to `other` then you can specify the custom styled separator here |
75
- | levels | String: heading levels to target `1-6` |
76
- | | Object: start and finish for custom range |
77
- | scope | the element to narrow it down to. `#main` is the default scope |
78
- | debug | `true` or `false` if you want to see `console.log` info |
66
+ There are several options available for the docsify-auto-headers plugin:
79
67
 
80
- ### Usage
68
+ | Setting | Type | Options |
69
+ |-------------|---------|-------------------------------------|
70
+ | `separator` | String | e.g., `.`, `-`, `)` |
71
+ | `sidebar` | Boolean | `true` or `false` |
72
+ | `levels` | Number | `1` to `6` |
73
+ | | Object | `{ start: Number, finish: Number }` |
74
+ | `debug` | Boolean | `true` or `false` |
81
75
 
82
- At the top of your file add the following snippet:
76
+ ## Usage
83
77
 
84
- ```md
85
- @autoHeader:#
86
- ```
87
-
88
- 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.
89
-
90
- It accepts only numbers.
91
-
92
- You can have a starting header at `0` using:
93
-
94
- ```md
95
- @autoHeader:0
96
- ```
78
+ The plugin can be configured to apply scoped heading counts in either the sidebar or the main content, depending on your setup.
97
79
 
98
- ## Customising individual numbers
80
+ ### Adding the signifier
99
81
 
100
- You can also manually set the starting number of each of the levels by using the following format:
82
+ When you want to use the heading numbering on a markdown file you can add either of the following signifiers to the **first line** of the document:
101
83
 
102
84
  ```md
103
- @autoheaders:3.5.6.6.1.12
104
-
105
- ##### New heading
85
+ @autoHeader:
106
86
  ```
107
87
 
108
- Respectively starting the first level 6 heading (H6) at:
109
-
110
88
  ```md
111
- 3.5.6.6.2.1 New heading
112
- ```
113
-
114
- ## Start and finish range
115
-
116
- You can also target specific heading levels for the numbering which works well if you want to skip H1.
117
-
118
- ```js
119
- <script>
120
- window.$docsify = {
121
- autoHeaders: {
122
- separator: 'other',
123
- custom: '--',
124
- levels: {
125
- start: '2',
126
- finish: '4'
127
- },
128
- scope: '#main',
129
- debug: false
130
- }
131
- };
132
- </script>
89
+ <!-- autoHeader: -->
133
90
  ```
134
91
 
135
- ```md
136
- @autoheaders:1.2.3.4.5.6
137
-
138
- # Level 1 heading
92
+ After the colon (`:`) you can add in the number that will begin for heading level 1 (`H1`).
139
93
 
140
- ## Level 2 heading
94
+ ### Sidebar
141
95
 
142
- ### Level 3 heading
143
- ```
96
+ If the `sidebar` option is enabled, the headers will be included in the sidebar and processed before rendering the markdown.
144
97
 
145
- ```md
146
- Level 1 heading
98
+ ### Main Content
147
99
 
148
- 1-- Level 2 heading
149
-
150
- 1--2-- Level 3 heading
151
- ```
152
-
153
- !> **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`
100
+ If the `sidebar` option is disabled, the headers will be processed and applied directly to the HTML after rendering.
154
101
 
155
102
  ## Contributing
156
103
 
157
- 1. Clone the repo:
158
-
159
- `git clone https://github.com/markbattistella/docsify-autoHeaders.git`
160
-
161
- 1. Create your feature branch:
162
-
163
- `git checkout -b my-feature`
164
-
165
- 1. Commit your changes:
104
+ 1. Clone the repo:<br>`git clone https://github.com/markbattistella/docsify-auto-headers.git`
166
105
 
167
- `git commit -am 'Add some feature'`
106
+ 1. Create your feature branch:<br>`git checkout -b my-feature`
168
107
 
169
- 1. `Push` to the branch:
108
+ 1. Commit your changes:<br>`git commit -am 'Add some feature'`
170
109
 
171
- `git push origin my-new-feature`
110
+ 1. `Push` to the branch:<br>`git push origin my-new-feature`
172
111
 
173
112
  1. Submit the `pull` request