Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hairyf/markdown-it-vitepress-demo
markdown plugin for building demos in vitepress.
https://github.com/hairyf/markdown-it-vitepress-demo
Last synced: about 2 months ago
JSON representation
markdown plugin for building demos in vitepress.
- Host: GitHub
- URL: https://github.com/hairyf/markdown-it-vitepress-demo
- Owner: hairyf
- License: mit
- Created: 2023-05-26T17:03:17.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-28T03:59:15.000Z (2 months ago)
- Last Synced: 2024-10-28T07:16:09.130Z (2 months ago)
- Language: TypeScript
- Homepage: https://markdown-it-vitepress-demo.vercel.app
- Size: 563 KB
- Stars: 14
- Watchers: 1
- Forks: 2
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# markdown-it-vitepress-demo
[](https://www.npmjs.com/package/markdown-it-vitepress-demo)
`markdown-it-vitepress-demo` is a `markdown-it` plugin specifically designed for Vitepress demos. It converts code blocks in Markdown into references to the `` component. It does not generate UI itself but serves as a plugin for creating demo containers. This means that you need to implement and register the `` component yourself, and `markdown-it-vitepress-demo` makes this process easier.
With this plugin, you can use the `` tag in Markdown to reference a demo container. For example:
```html
```
You can use Markdown syntax in the `desc` field. For example:
```html
```
However, we recommend using the `container` mode to write the `desc` content with Markdown:
```markdown
::: demo src="../demo.vue" title="Demo block"
This is a `description` that can be written using Markdown.
:::
```
This looks more aesthetically pleasing and adheres better to Markdown syntax.
In addition, you can pass the `attrs` parameter to `props`, so you can utilize the [Line Highlighting in Code Blocks](https://vitepress.dev/guide/markdown#line-highlighting-in-code-blocks) feature of VitePress:
```markdown
```
Other `props` will not be processed and will be directly passed to the `` component. For example, you can customize whether the code is expanded using the `prop`:
```markdown
```
> however, it is important to note that `` is not strictly a component and cannot handle excessively complex custom `props`, such as `v-bind`.
## Install
```bash
npm install markdown-it-vitepress-demo --save-dev
```
## Usage
```js
// .vitepress/config.js
export default defineConfig({
markdown: {
config(md) {
md.use(require('markdown-it-vitepress-demo'))
},
},
})
```
Register your `` component in `theme/index.ts|js`:
```js
// https://vitepress.dev/guide/custom-theme
import Theme from 'vitepress/theme'
// your demo component
import CustomDemoContainer from './components/CustomDemoContainer.vue'
export default {
...Theme,
enhanceApp({ app, router, siteData }) {
app.component('demo-container', CustomDemoContainer)
},
}
```
The `demo-container` component will receive relevant information about the demo, and you need to implement the rendering of the demo:
```html
import { computed } from 'vue'
const props = defineProps<{
sfcTsCode: string
// if using ts, sfcJsCode will transform the to js
sfcJsCode: string
sfcTsHtml: string
sfcJsHtml: string
title: string
metadata: object
}>()
const sfcCode = computed(() => decodeURIComponent(props.sfcTsCode || props.sfcJsCode))
const highlightedHtml = computed(() => decodeURIComponent(props.sfcTsHtml || props.sfcJsHtml))
{{ title }}
Copy Code
```
## Metadata
The `demo-container` component will receive relevant information about the demo. You can use the `metadata` to access and use this information within the demo:
```html
const props = defineProps<{
sfcTsCode: string
sfcJsCode: string
sfcTsHtml: string
sfcJsHtml: string
title: string
// metadata returns information about the demo during build (absolutePath, relativePath, fileName)
metadata: object
}>()
const githubBlobUrl = 'https://www.github.com/.../tree/main/'
const githubPath = githubBlobUrl + props.metadata.relativePath
function toEditGithubDemoFile() {
window.open(githubPath)
}
```
## CodeSandbox
You can define the parameters for CodeSandbox by using `codesandbox/lib/api/define` and create a sandbox environment by submitting them to the CodeSandbox API through a ``:
```html
import { getParameters } from 'codesandbox/lib/api/define'
const props = defineProps<{
sfcTsCode: string
sfcJsCode: string
// ...
}>()
// Compute the parameters for CodeSandbox
const parameters = computed(() => {
return getParameters({
files: {
'package.json': {
// specify your dependencies
content: { dependencies: { vue: 'latest' } },
},
'index.html': { content: `<div id="app"></div>` },
'App.vue': { content: decodeURIComponent(props.sfcJsCode) },
'src/main.js': { content: '...' },
},
})
})
Edit in CodeSandbox
```
## Development
```bash
pnpm install
# Run development server
pnpm dev
# Have fun!
pnpm play
```
> Unit tests are in progress, PRs welcome!
## Acknowledgements
This project draws inspiration from the following projects:
- [ruabick](https://github.com/dewfall123/ruabick)
- [vitepress-demo-preview](https://github.com/flingyp/vitepress-demo-preview)
- [create-vitepress-demo](https://github.com/bowencool/create-vitepress-demo)
- [naive-ui](https://github.com/tusen-ai/naive-ui)
- [element-plus](https://github.com/element-plus/element-plus)
## License
[MIT](./LICENSE) License © 2022 [Hairyf](https://github.com/hairyf)