vue-markdown-shiki v1.4.6
Vue 3 Component Library with Shiki and Markdown-it Integration
This is a Vue 3 component library that provides integration with Shiki and Markdown-it.
Shiki is an efficient code syntax highlighter, while Markdown-it is a popular Markdown parser. With Vue 3 integration, this library offers customizable code highlighting and Markdown parsing, making it easy to build beautiful and highly customizable web applications.
✨ Features
- Vue 3 integration for easy component development
- Shiki integration for efficient code syntax highlighting
- Markdown-it integration for powerful Markdown parsing
- Customizable code highlighting and Markdown parsing options
- Copy and download functionality
- Two components provided:
VueMarkdownIt
andVueMarkDownHeader
VueMarkdownIt
renders native Markdown strings and includesVueMarkDownHeader
by defaultVueMarkDownHeader
provides a menu for copy and download functionalityVueMarkdownItProvider
a wrapper for async use, provides a globalmd
instance for MarkdownIt.
🌈 Motion
The initial intention behind this project:
After noticing the attractive code highlighting provided by Shiki in Vitepress, I started looking for a corresponding Vue component solution. However, I found that there weren't any satisfactory solutions for non-server-side rendering. As a result, I decided to create a plugin called vue-markdown-shiki. I hope everyone will find it useful and enjoyable.
If you are looking for a Node.js solution(SSR), you may consider using markdown-it-shiki.
Completed features:
- Vue components that can be used out-of-the-box
- Extended support for markdownIt properties
- ChatGPT stream-style output display
- Customizable code block slot
- Code block header that allows for download and copying
Next development plan:
- Optimization for SSR scenarios
- Provide sample projects for frameworks such as Nuxt.
📝 Intro
VueMarkdownIt
options:
content
: A required prop that specifies the Markdown content to render.style
: An optional prop that allows you to add custom styles to the rendered Markdown.class
: An optional prop that allows you to add custom CSS classes to the rendered Markdown.stream
: An optional prop that specifies whether the Markdown should be rendered as a stream. When set totrue
, the Markdown will be rendered as it is streamed in, rather than all at once. This can be useful for rendering large documents. The default value isfalse
.
You can use these props to customize the appearance and behavior of the rendered Markdown. For example, you could use the style
prop to change the font size or color of the rendered Markdown, or the class
prop to add a custom CSS class that applies specific styling. The stream
prop can be useful when rendering very large Markdown documents, as it can improve performance by rendering the document in smaller chunks.
🚀 Getting Started
To use this component library in your Vue 3 project, follow these steps:
Install the library using
npm
oryarn
:npm install vue-markdown-shiki
or
yarn add vue-markdown-shiki
Import the components you need in your Vue 3 project, modify
main.ts
:import 'vue-markdown-shiki/style' import markdownPlugin from 'vue-markdown-shiki' app.use(markdownPlugin)
You can also use
app.use(markdownPlugin, options)
to pass anoptions
parameter, which can accept the following:The
MarkdownOptions
interface extends theMarkdownIt.Options
interface, which provides options for configuring the Markdown-it parser. In addition to the base options,MarkdownOptions
provides the following options:lineNumbers
: A boolean that specifies whether line numbers should be added to the code blocks.config
: A function that accepts theMarkdownIt
instance and allows you to configure it.anchor
: An object of options for themarkdown-it-anchor
plugin, which adds anchors to the headings in the Markdown.attrs
: An object of options for themarkdown-it-attrs
plugin, which allows you to add custom attributes to elements in the Markdown.defaultHighlightLang
: A string that specifies the default language for code blocks to be highlighted with.headers
: An object of options for themarkdown-it-anchor
plugin, which adds anchors to the headings in the Markdown. If set tofalse
, the plugin will be disabled.theme
: An object of options for themarkdown-it-highlightjs-theme
plugin, which allows you to customize the theme used for code highlighting.languages
: An array of objects that register additional languages for highlighting with themarkdown-it-highlight
plugin.toc
: An object of options for themarkdown-it-table-of-contents
plugin, which generates a table of contents for the Markdown.externalLinks
: An object that maps domain names to their corresponding URL prefixes, which are added to external links in the Markdown.
These options can be passed to the
app.use(markdownPlugin, options)
method to configure themarkdown-it
parser used by theVueMarkdownIt
component.TIPS: Why do we need to use
app.use
to globally initialize the instance here?This is because it allows us to avoid repeatedly loading the language JSON when rendering Markdown strings, so it is strongly recommended to initialize globally. If you think that initializing during page loading is not elegant, you can use async components. See the example.
a. define a new
MD.vue
in your project:<script setup lang="ts"> import {VueMarkdownItProvider, VueMarkdownIt} from 'vue-markdown-shiki' </script> <template> <VueMarkdownItProvider> <VueMarkdownIt :content="str" :stream="stream" ref="md" :class="theme"> </VueMarkdownIt> </VueMarkdownItProvider> </template>
b. use async component for
MD.vue
:<script> import { defineAsyncComponent } from 'vue' export default { components: { AdminPage: defineAsyncComponent(() => import('./components/MD.vue') ) } } </script>
Copy Assets:
Vite-plugin:
npm install -D vite-plugin-forvmsc
Modify your
vite.config.*
file:import { copyPublicPlugin } from 'vite-plugin-forvmsc' export default defineConfig(() => { // ... plugins: [ // ... // add this line: copyPublicPlugin() })
Manually:
node_modules/vue-markdown-shiki/public/*
, to your vue3 project'spublic
directory.
Use the components in your Vue 3 templates:
import { VueMarkdownIt } from 'vue-markdown-shiki' <template> <div> <VueMarkdownIt :content="'your-raw-markdown-string'" /> </div> </template>
For more detailed usage instructions, please see the Example.
Contributing
Contributions are welcome! If you find a bug or have a feature request, please open an issue on GitHub. If you'd like to contribute code, please fork the repository and submit a pull request.
License
This component library is licensed under the MIT License.