@markbattistella/docsify-autoheaders 5.0.0 → 5.0.1
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.
- package/CHANGELOG.md +6 -0
- package/README.md +53 -128
- package/dist/docsify-auto-headers.js +1 -1
- package/dist/docsify-auto-headers.min.js +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
package/README.md
CHANGED
|
@@ -1,173 +1,98 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
# docsify
|
|
4
|
-
|
|
5
|
-
   
|
|
6
|
-
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
[](https://www.paypal.me/markbattistella/6AUD)
|
|
10
|
-
[](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 utilizing this plugin, you can easily manage and navigate through your documentation headers, ensuring consistency and improved readability.
|
|
17
8
|
|
|
18
|
-
|
|
9
|
+
## Demo pages
|
|
19
10
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
11
|
+
| Page link | Description |
|
|
12
|
+
|-|-|
|
|
13
|
+
| [](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
|
+
| [](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
|
+
| [](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
|
+
| [](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
|
+
| [](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
|
|
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 -->
|
|
34
|
-
<script src="https://unpkg.com/@markbattistella/docsify-
|
|
31
|
+
<script src="https://unpkg.com/@markbattistella/docsify-auto-headers@latest"></script>
|
|
35
32
|
|
|
36
33
|
<!-- jsDelivr -->
|
|
37
|
-
<script src="https://cdn.jsdelivr.net/npm/@markbattistella/docsify-
|
|
34
|
+
<script src="https://cdn.jsdelivr.net/npm/@markbattistella/docsify-auto-headers@latest"></script>
|
|
38
35
|
|
|
39
36
|
<!-- locally -->
|
|
40
|
-
<script src="docsify-
|
|
37
|
+
<script src="docsify-auto-headers.min.js"></script>
|
|
41
38
|
```
|
|
42
39
|
|
|
43
|
-
1. In docsify setup configure the plugin
|
|
44
|
-
|
|
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
|
-
```
|
|
58
|
-
|
|
59
|
-
### npm install
|
|
60
|
-
|
|
61
|
-
Or if you're using `npm` to manage your dependencies:
|
|
62
|
-
|
|
63
|
-
```sh
|
|
64
|
-
npm i @markbattistella/docsify-autoheaders
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
### Configuration
|
|
68
|
-
|
|
69
|
-
There are some options available for the `docsify-autoHeaders`:
|
|
70
|
-
|
|
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 |
|
|
79
|
-
|
|
80
|
-
### Usage
|
|
40
|
+
1. In docsify setup, configure the plugin:
|
|
81
41
|
|
|
82
|
-
|
|
42
|
+
```js
|
|
43
|
+
<script>
|
|
44
|
+
window.$docsify = {
|
|
45
|
+
autoHeaders: {
|
|
83
46
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
```
|
|
47
|
+
// Separator for header numbering (e.g., '.', '-', ')')
|
|
48
|
+
separator: '.',
|
|
87
49
|
|
|
88
|
-
|
|
50
|
+
// Boolean indicating if headers should be added to the sidebar
|
|
51
|
+
sidebar: false,
|
|
89
52
|
|
|
90
|
-
|
|
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 }
|
|
91
56
|
|
|
92
|
-
|
|
57
|
+
// Boolean to enable or disable debug messages
|
|
58
|
+
debug: false
|
|
59
|
+
}
|
|
60
|
+
};
|
|
61
|
+
</script>
|
|
62
|
+
```
|
|
93
63
|
|
|
94
|
-
|
|
95
|
-
@autoHeader:0
|
|
96
|
-
```
|
|
64
|
+
## Configuration
|
|
97
65
|
|
|
98
|
-
|
|
66
|
+
There are several options available for the docsify-auto-headers plugin:
|
|
99
67
|
|
|
100
|
-
|
|
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` |
|
|
101
75
|
|
|
102
|
-
|
|
103
|
-
@autoheaders:3.5.6.6.1.12
|
|
76
|
+
## Usage
|
|
104
77
|
|
|
105
|
-
|
|
106
|
-
```
|
|
78
|
+
The plugin can be configured to apply scoped heading counts in either the sidebar or the main content, depending on your setup.
|
|
107
79
|
|
|
108
|
-
|
|
80
|
+
### Sidebar
|
|
109
81
|
|
|
110
|
-
|
|
111
|
-
3.5.6.6.2.1 New heading
|
|
112
|
-
```
|
|
82
|
+
If the `sidebar` option is enabled, the headers will be included in the sidebar and processed before rendering the markdown.
|
|
113
83
|
|
|
114
|
-
|
|
84
|
+
### Main Content
|
|
115
85
|
|
|
116
|
-
|
|
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>
|
|
133
|
-
```
|
|
134
|
-
|
|
135
|
-
```md
|
|
136
|
-
@autoheaders:1.2.3.4.5.6
|
|
137
|
-
|
|
138
|
-
# Level 1 heading
|
|
139
|
-
|
|
140
|
-
## Level 2 heading
|
|
141
|
-
|
|
142
|
-
### Level 3 heading
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
```md
|
|
146
|
-
Level 1 heading
|
|
147
|
-
|
|
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`
|
|
86
|
+
If the `sidebar` option is disabled, the headers will be processed and applied directly to the HTML after rendering.
|
|
154
87
|
|
|
155
88
|
## Contributing
|
|
156
89
|
|
|
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:
|
|
90
|
+
1. Clone the repo:<br>`git clone https://github.com/markbattistella/docsify-auto-headers.git`
|
|
166
91
|
|
|
167
|
-
|
|
92
|
+
1. Create your feature branch:<br>`git checkout -b my-feature`
|
|
168
93
|
|
|
169
|
-
1.
|
|
94
|
+
1. Commit your changes:<br>`git commit -am 'Add some feature'`
|
|
170
95
|
|
|
171
|
-
|
|
96
|
+
1. `Push` to the branch:<br>`git push origin my-new-feature`
|
|
172
97
|
|
|
173
98
|
1. Submit the `pull` request
|
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
/*! docsify-auto-headers 5.0.
|
|
1
|
+
/*! docsify-auto-headers 5.0.1 | (c) Mark Battistella */
|
|
2
2
|
"use strict";function ownKeys(r,e){var t,n=Object.keys(r);return Object.getOwnPropertySymbols&&(t=Object.getOwnPropertySymbols(r),e&&(t=t.filter(function(e){return Object.getOwnPropertyDescriptor(r,e).enumerable})),n.push.apply(n,t)),n}function _objectSpread(r){for(var e=1;e<arguments.length;e++){var t=null!=arguments[e]?arguments[e]:{};e%2?ownKeys(Object(t),!0).forEach(function(e){_defineProperty(r,e,t[e])}):Object.getOwnPropertyDescriptors?Object.defineProperties(r,Object.getOwnPropertyDescriptors(t)):ownKeys(Object(t)).forEach(function(e){Object.defineProperty(r,e,Object.getOwnPropertyDescriptor(t,e))})}return r}function _defineProperty(e,r,t){return(r=_toPropertyKey(r))in e?Object.defineProperty(e,r,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[r]=t,e}function _toPropertyKey(e){e=_toPrimitive(e,"string");return"symbol"==_typeof(e)?e:e+""}function _toPrimitive(e,r){if("object"!=_typeof(e)||!e)return e;var t=e[Symbol.toPrimitive];if(void 0===t)return("string"===r?String:Number)(e);t=t.call(e,r||"default");if("object"!=_typeof(t))return t;throw new TypeError("@@toPrimitive must return a primitive value.")}function _createForOfIteratorHelper(e,r){var t,n,o,a,i="undefined"!=typeof Symbol&&e[Symbol.iterator]||e["@@iterator"];if(i)return o=!(n=!0),{s:function(){i=i.call(e)},n:function(){var e=i.next();return n=e.done,e},e:function(e){o=!0,t=e},f:function(){try{n||null==i.return||i.return()}finally{if(o)throw t}}};if(Array.isArray(e)||(i=_unsupportedIterableToArray(e))||r&&e&&"number"==typeof e.length)return i&&(e=i),a=0,{s:r=function(){},n:function(){return a>=e.length?{done:!0}:{done:!1,value:e[a++]}},e:function(e){throw e},f:r};throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}function _toConsumableArray(e){return _arrayWithoutHoles(e)||_iterableToArray(e)||_unsupportedIterableToArray(e)||_nonIterableSpread()}function _nonIterableSpread(){throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}function _iterableToArray(e){if("undefined"!=typeof Symbol&&null!=e[Symbol.iterator]||null!=e["@@iterator"])return Array.from(e)}function _arrayWithoutHoles(e){if(Array.isArray(e))return _arrayLikeToArray(e)}function _slicedToArray(e,r){return _arrayWithHoles(e)||_iterableToArrayLimit(e,r)||_unsupportedIterableToArray(e,r)||_nonIterableRest()}function _nonIterableRest(){throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.")}function _unsupportedIterableToArray(e,r){var t;if(e)return"string"==typeof e?_arrayLikeToArray(e,r):"Map"===(t="Object"===(t={}.toString.call(e).slice(8,-1))&&e.constructor?e.constructor.name:t)||"Set"===t?Array.from(e):"Arguments"===t||/^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t)?_arrayLikeToArray(e,r):void 0}function _arrayLikeToArray(e,r){(null==r||r>e.length)&&(r=e.length);for(var t=0,n=Array(r);t<r;t++)n[t]=e[t];return n}function _iterableToArrayLimit(e,r){var t=null==e?null:"undefined"!=typeof Symbol&&e[Symbol.iterator]||e["@@iterator"];if(null!=t){var n,o,a,i,u=[],s=!0,c=!1;try{if(a=(t=t.call(e)).next,0===r){if(Object(t)!==t)return;s=!1}else for(;!(s=(n=a.call(t)).done)&&(u.push(n.value),u.length!==r);s=!0);}catch(e){c=!0,o=e}finally{try{if(!s&&null!=t.return&&(i=t.return(),Object(i)!==i))return}finally{if(c)throw o}}return u}}function _arrayWithHoles(e){if(Array.isArray(e))return e}function _typeof(e){return(_typeof="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e})(e)}!function(){function e(e,r){function y(e,r){return e&&console.warn("Docsify Auto Headers:\n>> ".concat(r)),m=!1,null}function h(e,r){if("number"!=typeof e&&("object"!==_typeof(e)||null===e))return y(r.debug,u);function t(e,r,t){return r<=e&&e<=t}var n,o;if("number"==typeof e)n=1,o=e;else if("object"===_typeof(e)){if(n=e.start,o=e.finish,"number"!=typeof n||"number"!=typeof o)return y(r.debug,s);if(o<n)return y(r.debug,c)}if(!t(n,1,6)||!t(o,1,6))return y(r.debug,l);for(var a={},i=1;i<=6;i++)a["h".concat(i)]={inScope:t(i,n,o)};return a}function d(e,r){var t=e.split(r.separator).map(function(e){return e.trim()});if(6<t.length)return y(r.debug,i);var n=t.every(function(e){return/^\d+$/.test(e)}),o=t.every(function(e){return/^[a-z]+$/.test(e)}),e=t.every(function(e){return/^[A-Z]+$/.test(e)});if(!n&&!o&&!e)return y(r.debug,f);for(;t.length<6;)t.push(n?"1":o?"a":"A");var a=n?"numeric":o?"alphabetic-lower":"alphabetic-upper";return t.map(function(e){return{counter:function(e,r){if("numeric"===r)return parseInt(e,10);e=e.toUpperCase();for(var t=0,n=0;n<e.length;n++)t=(t*=26)+(e.charCodeAt(n)-65+1);return t}(e,a),type:a}})}function n(e,r,t,n){var i,u,s,c,o=g(e),a=o.currentCounts,l=o.scopedTagNames;return"html"===n?(_toConsumableArray((t=(new DOMParser).parseFromString(t,"text/html").body).querySelectorAll("h1, h2, h3, h4, h5, h6")).forEach(function(e){return function(e,r){var t=this.currentCounts,n=this.scopedTagNames,o=e.tagName.toLowerCase(),a=["h1","h2","h3","h4","h5","h6"],i=t.get(o);i.current+=1,i.skipDownstreamReset||a.slice(a.indexOf(o)+1).forEach(function(e){t.has(e)&&(t.get(e).current=0)}),i.skipDownstreamReset=!1,n.has(o)&&(i=a.slice(0,a.indexOf(o)+1).map(function(e){var e=t.get(e),r=e.current,e=e.type;return v(r,e)}).join(r.separator)+r.separator,e.innerHTML="".concat(i," ").concat(e.innerHTML))}.call({currentCounts:a,scopedTagNames:l},e,r)}),t.innerHTML):"markdown"===n?(o=t,i=r,n=g(n=e),u=n.currentCounts,s=n.scopedTagNames,c=["h1","h2","h3","h4","h5","h6"],o.replace(/^(#{1,6})\s+(.*)$/gm,function(e,r,t){var n=r.length,o="h".concat(n),a=u.get(o);return a.current+=1,a.skipDownstreamReset||c.slice(n).forEach(function(e){u.has(e)&&(u.get(e).current=0)}),a.skipDownstreamReset=!1,s.has(o)?(a=c.slice(0,n).map(function(e){var e=u.get(e),r=e.current,e=e.type;return v(r,e)}).join(i.separator)+i.separator,"".concat(r," ").concat(a," ").concat(t)):e})):void 0}var p,t,o="Configuration settings are not set correctly. Please review the autoHeaders parameters and documentation.",a="The sidebar setting for autoHeaders only accepts a boolean of true or false. Please check you've entered this data correctly.",u="The levels settings for autoHeaders only accepts a number from 1-6 or an object with the start and finish options. Please check you've entered this data correctly.",s="The levels setting has been configured with a start and finish option. However, the values for one of these is not a number. Please check you've entered this data correctly.",c="The levels setting has been configured with a start and finish option. However, the start value is greater than the finish. Please check you've entered this data correctly.",l="The levels setting has been configured with a start and finish option. However, the values for one of these is not from 1-6. Please check you've entered this data correctly.",i="The elements found in the signifier have equated to more than 6 headings. Please check the configuration of your markdown that you have no more than 6 numbers",f="The elements found in the signifier are not numbers only or alphabet only. Please check the configuration of your markdown that all the items are numeric or alphabetic.",b="The current markdown file is missing the @autoHeader: or \x3c!-- autoHeader: --\x3e signifier",m=!0,v=function(e,r){if("numeric"===r)return e+"";e--;for(var t="";0<=e;){t=String.fromCharCode(65+e%26)+t;e=Math.floor(e/26)-1}return"alphabetic-lower"===r?t.toLowerCase():t},g=function(e){e=Object.entries(e);return{currentCounts:new Map(e.map(function(e){var e=_slicedToArray(e,2),r=e[0],e=e[1],t=e.counter,e=e.type,t=parseInt(t,10);return[r,{current:Number.isFinite(t)?t-1:0,type:e,skipDownstreamReset:!0}]})),scopedTagNames:new Set(e.filter(function(e){e=_slicedToArray(e,2);e[0];return e[1].inScope}).map(function(e){return _slicedToArray(e,1)[0]}))}},w=(t=_).separator&&void 0!==t.levels?{separator:{decimal:".",dot:".",dash:"-",hyphen:"-",bracket:")",parenthesis:")"}[t.separator]||t.separator,levels:t.levels||6,sidebar:!!t.sidebar,debug:!!t.debug}:y(t.debug,o);w&&(p={separator:w.separator,levels:h(w.levels,w),sidebar:(t=w.sidebar,o=w,"boolean"!=typeof t?y(o.debug,a):t),debug:w.debug},e.beforeEach(function(e){if(m=!0){r=p;var r,t=(t=(n=e).match(/^\s*(?:@autoHeader:|<!--\s+autoHeader:)([\d.a-zA-Z\-:,~]*)(?:\s+-->)?/))?(n=n.substring(t[0].length),{headingSignifier:t[1],markdown:n}):y(r.debug,b);if(t){var n=t.headingSignifier,o=(e=t.markdown,h(w.levels,p));if(o){var a=d(n,p);if(a){var i,u={},s=_createForOfIteratorHelper(Object.keys(o).entries());try{for(s.s();!(i=s.n()).done;){var c=_slicedToArray(i.value,2),l=c[0],f=c[1];u[f]=_objectSpread(_objectSpread({},o[f]),a[l])}}catch(e){s.e(e)}finally{s.f()}p.levels=u}}}}return e}),p.sidebar?e.beforeEach(function(r,e){var t;try{t=n(p.levels,p,r,"markdown"),m||(t=r)}catch(e){t=r,console.warn(e.message)}finally{e(t)}}):e.afterEach(function(r,e){var t;try{t=n(p.levels,p,r,"html"),m||(t=r)}catch(e){t=r,console.warn(e.message)}finally{e(t)}}))}var _={separator:".",sidebar:!1,levels:6,debug:!1};window&&(window.$docsify=window.$docsify||{},window.$docsify.autoHeaders=Object.assign(_,window.$docsify.autoHeaders),window.$docsify.plugins=(window.$docsify.plugins||[]).concat(e))}();
|