@uniob/markdown-it-shiki v0.8.0-r8
markdown-it-shiki
Markdown It plugin for Shiki
Install
npm i -D markdown-it-shiki
Usage
import MarkdownIt from 'markdown-it'
import Shiki from 'markdown-it-shiki'
const md = MarkdownIt()
md.use(Shiki, {
theme: 'nord'
})
Dark mode
md.use(Shiki, {
theme: {
dark: 'min-dark',
light: 'min-light'
}
})
Add then these to your CSS
/* Query based dark mode */
@media (prefers-color-scheme: dark) {
.shiki-light {
display: none;
}
}
@media (prefers-color-scheme: light), (prefers-color-scheme: no-preference) {
.shiki-dark {
display: none;
}
}
/* Class based dark mode */
html.dark .shiki-light {
display: none;
}
html:not(.dark) .shiki-dark {
display: none;
}
Highlight lines
md.use(Shiki, {
highlightLines: true
})
Add these to your CSS
code[v-pre] {
display: flex;
flex-direction: column;
}
.shiki .highlighted {
background: #7f7f7f20;
display: block;
margin: 0 -1rem;
padding: 0 1rem;
}
Then you can highlight lines in code block.
```js {1-2}
const md = new MarkdownIt()
md.use(Shiki)
const res = md.render(/** ... */)
console.log(res)
```
Generic Prepending and Appending Extra
You can add extra html tags at the beginning or end of the code block by specifying the extra
option field, illustrated in the following example:
```html
<div class="shiki-container">
<!-- extra html tags prepended -->
<pre class="shiki">
<code>
...
</code>
</pre>
<!-- extra html tags appended -->
</div>
Extra tag processors are specified the extra processors in the extra
option field. For example,
import { FilenameProcessor } from '@uniob/markdown-it-shiki/utils'
md.use(Shiki, {
extra: [FilenameProcessor]
})
If the code block is written in the following format:
```js {1-2} filename="index.js"
const md = new MarkdownIt()
md.use(Shiki)
```
the result of adding FilenameProcessor
will be
<div class="shiki-container">
<div class="shiki-filename">index.js</div>
<pre class="shiki">
<code>
...
</code>
</pre>
<!-- extra html tags appended -->
</div>
The actual code block content might have gap between the prepended and appended extra tags. This is probably due to user agent default styling. You can add the following css to fix this issue:
.shiki-container pre.shiki {
margin: 0;
}
There are four positions you can append, 'before', 'after', 'ftop_right', 'f_bottom_right', 'f_top_left', 'f_bottom_left'. The 'before' and 'after' positions will direct the extra tag to be prepended or appended to the actual code block. The positions with names starting with 'f' will direct the extra tag to floated on the according corners. You need to add the following CSS to your stylesheet. Every class except shiki-float-hide
is added automatically.
div.shiki-container {
--shiki-float-visible: none;
--float-right-dist: 10px;
--float-top-dist: 10px;
--float-bottom-dist: 10px;
--float-left-dist: 10px;
}
div.shiki-container:hover {
--shiki-float-visible: block;
}
.shiki-float {
position: absolute;
}
.shiki-float-right {
right: var(--float-right-dist);
}
.shiki-float-top {
top: var(--float-top-dist);
}
.shiki-float-bottom {
bottom: var(--float-bottom-dist);
}
.shiki-float-left {
left: var(--float-left-dist);
}
.shiki-float-hide {
display: var(--shiki-float-visible)
}
An extra
processor has the following type:
interface ExtraProcessor {
light: Processor
dark?: Processor | null
position: ExtraPosition
attrRe?: RegExp
}
where attrRe
is the regex expression that matches the attributes passed into the code block, which is the string right after the first triple tilda.
```html {1-2} filename="hi.html"
```
light
and dark
are function that takes in a RegExpExecArray
or null
and returns a ElementIntel
object which will be turned into a html tag string later in the processing pipeline. null
is pass to the processor only when the attrRe
did not match anything or the attrRe
is undefined. An ElementIntel
object has the following type
interface IElementIntel {
tag: string
attrs: Record<string, string>
content?: string | IElementIntel
}
If dark
is undefined, then the light
will be reused for the dark theme. If dark
is null
, then the processor will not be applied to the dark theme. The position
field specifies where the processor should be applied. ExtraPosition.before
and ExtraPosition.after
are the only two options available for now, which will prepend and append, respectively, the extra html tags with respect to the actual code block.