https://github.com/langworr/markdown-it-analytical-index
Create automaticaly an analytical index in Markdown documents using markdown-it.
https://github.com/langworr/markdown-it-analytical-index
markdown markdown-it-plugin
Last synced: 3 months ago
JSON representation
Create automaticaly an analytical index in Markdown documents using markdown-it.
- Host: GitHub
- URL: https://github.com/langworr/markdown-it-analytical-index
- Owner: langworr
- License: mit
- Created: 2025-08-08T07:49:56.000Z (9 months ago)
- Default Branch: dev-ts
- Last Pushed: 2025-08-08T10:03:16.000Z (9 months ago)
- Last Synced: 2025-08-08T12:14:47.008Z (9 months ago)
- Language: JavaScript
- Size: 48.8 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# markdown-it-analytical-index
[](https://www.npmjs.com/package/markdown-it-analytical-index)
[](https://www.npmjs.com/package/markdown-it-analytical-index)
[](LICENSE)
[](https://www.typescriptlang.org/)
A plugin for [markdown-it](https://github.com/markdown-it/markdown-it) that generates a semantic analytical index based on specially marked terms within the Markdown text.
The plugin detects words marked with a customizable marker and wraps them in HTML tags with unique anchors, then creates a list of references at a designated placeholder location using ``.
---
## Installation
Install via npm:
```bash
npm install markdown-it-analytical-index
```
---
## Basic Usage
```js
const MarkdownIt = require("markdown-it")
const analyticalIndex = require("markdown-it-analytical-index")
const md = new MarkdownIt({ html: true })
.use(analyticalIndex, {
marker: "!!", // Optional marker, "!!" is the default.
headingLevel: 3, // Optional heading level (defaults to h2).
sortOrder: "alphabetical" // Optional sort order: "occurrence" | "alphabetical"
// Default is "alphabetical"
})
const input = `
This sentence contains [[symmetry]] and also [[contrast]].
`
const output = md.render(input)
```
---
## Supported Syntax
| Input | Description |
|---|---|
| `[[Term]]` | Highlights the term and links it in the index |
| `` | Placeholder for the index location and its title.
If the title is not specified, it will be "Analytical Index".
If the placeholder is not present, the index will not appear. |
---
## Options
Pass an object when registering the plugin to customize output:
| Option | Type | Default | Description |
|----------------|----------|--------------------|----------------------------------------------------------------|
| `marker` | string | `"!!"` | Marker for terms (e.g. `!!` for `!![term]` or use `[[term]]` by default) |
| `headingLevel` | number | `2` | HTML heading level for the index title (e.g. `h2`, `h3`) |
| `sortOrder` | `"occurrence" \| "alphabetical"` | `"alphabetical"` | Order the terms by occurrence number or alphabetically |
---
## HTML Output Example
Given this Markdown:
```markdown
Here is a concept: [[symmetry]] and another: [[contrast]].
```
The plugin will render HTML similar to:
```html
Here is a concept: symmetry and another:
contrast
Cool index
Symmetry → 1
Contrast → 1
```
Each term receives a unique anchor and is listed with clickable references in the index.
---
## Notes
- The index is generated **only** if the special comment `` (with or with a title) is present in the Markdown.
- The index title can be set with the placeholder comment.
- If no bracketed terms are found, the index is not rendered.
- The plugin supports multiple references to the same term and automatically increments the index.
---
## License
MIT — free to use, modify, and distribute.
---
## Author
Created by Roberto.