Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/norskeld/shikigami
Opinionated syntax highlighting with shiki for markdown-it.
https://github.com/norskeld/shikigami
hacktoberfest markdown markdown-it markdown-it-plugin shiki syntax-highlighting typescript
Last synced: 3 months ago
JSON representation
Opinionated syntax highlighting with shiki for markdown-it.
- Host: GitHub
- URL: https://github.com/norskeld/shikigami
- Owner: norskeld
- License: mit
- Created: 2022-01-05T20:14:18.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2024-04-16T11:35:15.000Z (10 months ago)
- Last Synced: 2024-11-13T10:52:54.738Z (3 months ago)
- Topics: hacktoberfest, markdown, markdown-it, markdown-it-plugin, shiki, syntax-highlighting, typescript
- Language: TypeScript
- Homepage:
- Size: 1000 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# `式神` shikigami
[](https://github.com/norskeld/shikigami/actions 'Build and test workflows')
[](https://coveralls.io/github/norskeld/shikigami 'Test coverage')
[](https://npm.im/@nrsk/shikigami 'This package on NPM')
[](https://github.com/semantic-release/semantic-release 'This package uses semantic release to handle releasing, versioning, changelog generation and tagging')
Opinionated syntax highlighting with [shiki] for [markdown-it].
## Installation
Just use your favorite package manager.
```bash
npm i @nrsk/shikigami
```
This package comes both in **CommonJS** and **ESM** flavors. No additional steps required, just `import` or `require` it.
## Usage
> [!NOTE]\
> No styles provided by default, so you need to style everything yourself, using classes described below. There's an [example of CSS here][css-example] using Tailwind.
> [!WARNING]\
> Most likely this plugin is incompatible with other plugins that process fenced code blocks, e.g. **[markdown-it-attrs]**, which can be used to assign classes to elements and has similar syntax.
This package exposes a function named **shikigami**, which is a `Promise`, that resolves to a **markdown-it** plugin function. Hence, you must `await` it (or use `.then` syntax), and only then pass the resulting function to **markdown-it**.
Below is an example of usage.
```typescript
import { shikigami, loadTheme } from '@nrsk/shikigami'
import md from 'markdown-it'
async function processMarkdown(input) {
const parser = md('commonmark').use(
await shikigami({
withLanguage: true,
withLineNumbers: true,
highlightInvert: true,
highlighter: {
// All other shiki's highlighter options are available as well,
// so you can load additional languages and so on.
theme: await loadTheme('./theme/custom.json')
}
})
)
return parser.render(input)
}
```
## Markdown syntax
This plugin introduces a simple syntax extension for fenced code blocks, that allows you to change plugin options in-place. Options defined this way have precedence over plugin options.
````markdown
# Example
```typescript {{ : , : , ... }}
interface User {
id: number
firstName: string
lastName: string
role: string
}
```
````
## Options
List of options that can be passed to `shikigami` function. Options allowed to be used directly in Markdown through syntax extension are marked accordingly.
### `openToken?: string`
- **Default**: `{{`
- **Allowed in Markdown**: no
Use this option to change the opening token for extended Markdown syntax.
### `closeToken?: string`
- **Default**: `}}`
- **Allowed in Markdown**: no
Use this option to change the closing token for extended Markdown syntax.
### `withLanguage?: boolean`
- **Default**: `false`
- **Allowed in Markdown**: yes
Set to `true` to allow rendering a sibling `
` with a `language-` class. This is useful when you want to show the language specified in your fenced code block.
### `withLineNumbers?: boolean`
- **Default**: `false`
- **Allowed in Markdown**: yes
Set to `true` to render line numbers.
### `highlight?: Array>`
- **Default**: `[]`
- **Allowed in Markdown**: yes
Use this option to specify which lines or ranges of lines should be marked with specified highlighting class (or classes). These classes can be customized via `highlightClasses` and `highlightRangeClasses` options.
#### Examples
- Highlight lines **5** and **7**:
```
{{ highlight: [5, 7] }}
```
- Highlight lines **5**, **7**, and lines in range from **10** to **15**:
```
{{ highlight: [5, 7, [10, 15]] }}
```
### `highlightClasses?: Array`
- **Default**: `['highlight']`
- **Allowed in Markdown**: no
Use this option to customize classes for highlighted lines.
### `highlightRangeClasses?: HighlightRangeClasses`
- **Default**: `['highlight-start', 'highlight-inner', 'highlight-end']`
- **Allowed in Markdown**: no
Use this option to customize classes for highlighted ranges. Must be a tuple of exactly three elements.
#### Explanation
- The first class is assigned to the first line of a range.
- The second class is assigned to all lines between the first and the last line of a range. _This only applied if the range covers 3 and more lines._
- The third class is assigned to the last line of a range.
_Is this overkill? Probably..._
### `highlightInvert?: boolean`
- **Default**: `false`
- **Allowed in Markdown**: yes
Set to `true` to allow marking lines that are not highlighted with specified classes. These classes can be customised via `highlightInvertClasses`.
**Note: this will work only if `highlight` option is set to a non-empty array of lines.**
### `highlightInvertClasses?: Array`
- **Default**: `['highlight-invert']`
- **Allowed in Markdown**: no
Use this option to customize classes for unhighlighted lines.
### `highlighter?: HighlighterOptions`
- **Default**: `{}`
- **Allowed in Markdown**: no
Highlighter options which will be passed right into shiki's `getHighlighter`. See [shiki documentation][shiki-docs] for available options.
## API
Besides exposing the `shikigami` function, this plugin re-exports shiki's `loadTheme` just for convenience.
### `shikigami(userOptions?: ShikigamiOptions): Promise`
Plugin factory function that resolves to a **markdown-it** plugin.
```typescript
import { shikigami } from '@nrsk/shikigami'
import anchor from 'markdown-it-anchor'
import md from 'markdown-it'
async function processMarkdown(input) {
return md('commonmark')
.use(
await shikigami({
/** Plugin options. */
})
)
.use(anchor)
.render(input)
}
```
### `loadTheme(themePath: string): Promise`
Shiki's theme loader.
## Todo
- [ ] Tests.
- [ ] Diffs support.
## License
[MIT](LICENSE).
[shiki]: https://shiki.matsu.io
[markdown-it]: https://github.com/markdown-it/markdown-it
[markdown-it-attrs]: https://github.com/arve0/markdown-it-attrs
[shiki-docs]: https://shiki.matsu.io
[css-example]: https://github.com/norskeld/vm.codes/blob/207e1759247861bbb0ab252827832e20f3760b5d/src/components/Content.astro#L20-L186