Skip to content

Commit d5010b5

Browse files
atinuxatinux
authored
docs: improve readme
1 parent f74d225 commit d5010b5

File tree

1 file changed

+75
-88
lines changed

1 file changed

+75
-88
lines changed

‎README.md

Lines changed: 75 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -46,93 +46,42 @@ export default defineNuxtConfig({
4646

4747
That's it! You can start writing and rendering markdown files ✨
4848

49-
## Parsing Markdown
50-
51-
Nuxt MDC exposes a handy helper to parse MDC files. You can import the `parseMarkdown` function from `@nuxtjs/mdc/runtime` and use it to parse markdown files written with MDC syntax.
52-
53-
### Node.js
54-
55-
```ts [/server/api/parse-mdc.ts]
56-
import { parseMarkdown } from '@nuxtjs/mdc/runtime'
57-
58-
export default eventHandler(async () => {
59-
const mdc = [
60-
'# Hello MDC',
61-
'',
62-
'::alert',
63-
'This is an Alert',
64-
'::'
65-
].join('\n')
49+
## Rendering
6650

67-
const ast = await parseMarkdown(mdc)
51+
`@nuxtjs/mdc` exposes three components to render markdown files.
6852

69-
return ast
70-
})
71-
```
53+
### `<MDC>`
7254

73-
### Browser
55+
Using `<MDC>`, you can parse and render markdown contents right inside your components/pages. This component takes raw markdown, parses it using the `parseMarkdown` function, and then renders it with `<MDCRenderer>`.
7456

75-
The `parseMarkdown` function is a universal helper, and you can also use it in the browser, for example inside a Vue component.
57+
```html
58+
<script setup lang="ts">
59+
const md = `
60+
::alert
61+
Hello MDC
62+
::
63+
`
64+
</script>
7665

77-
```vue [mdc-test.vue]
7866
<template>
79-
<div>This is a test</div>
67+
<MDC :value="md" tag="article" />
8068
</template>
81-
82-
<script setup lang="ts">
83-
import { parseMarkdown } from '@nuxtjs/mdc/runtime'
84-
85-
const props = defineProps({
86-
md: {
87-
type: String,
88-
default: () => '::alert\nMissing markdown input\n::'
89-
}
90-
})
91-
92-
const ast = await parseMarkdown(props.md)
93-
</script>
9469
```
9570

96-
### Options
97-
98-
The `parseMarkdown` helper also accepts options as the second argument to control the parser's behavior. (Checkout [`MDCParseOptions` interface↗︎](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/types/parser.ts)).
99-
100-
| Name | Default | Description |
101-
| -- | -- | -- |
102-
| `remark.plugins` | `{}` | Register / Configure parser's remark plugins. |
103-
| `rehype.options` | `{}` | Configure `remark-rehype` options. |
104-
| `rehype.plugins` | `{}` | Register / Configure parser's rehype plugins. |
105-
| `highlight` | `false` | Control whether code blocks should highlight or not. You can also provide a custom highlighter. |
106-
| `toc.depth` | `2` | Maximum heading depth to include in the table of contents. |
107-
| `toc.searchDepth` | `2` | Maximum depth of nested tags to search for heading. |
108-
109-
Checkout [`MDCParseOptions` types↗︎](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/types/parser.ts).
110-
111-
## Rendering (Vue)
112-
113-
`@nuxtjs/mdc` exposes three components to render markdown files.
114-
11571
### `<MDCRenderer>`
11672

11773
This component will take the result of [`parseMarkdown`](#parsing-markdown) function and render the contents. For example, this is an extended version of the sample code in the [Browser section](#browser) which uses `MDCRenderer` to render the parsed markdown.
11874

11975
```html [mdc-test.vue]
120-
<template>
121-
<MDCRenderer :body="ast.body" :data="ast.data" />
122-
</template>
123-
12476
<script setup lang="ts">
12577
import { parseMarkdown } from '@nuxtjs/mdc/runtime'
12678
127-
const props = defineProps({
128-
md: {
129-
type: String,
130-
default: () => '::alert\nMissing markdown input\n::'
131-
}
132-
})
133-
134-
const ast = await parseMarkdown(props.md)
79+
const ast = await useAsyncData('markdown', () => parseMarkdown('::alert\nMissing markdown input\n::'))
13580
</script>
81+
82+
<template>
83+
<MDCRenderer :body="ast.body" :data="ast.data" />
84+
</template>
13685
```
13786

13887
### `<MDCSlot>`
@@ -165,24 +114,6 @@ It is the default behavior of markdown to wrap every text inside a paragraph. MD
165114
</template>
166115
```
167116

168-
### `<MDC>`
169-
170-
Using `<MDC>`, you can parse and render markdown contents right inside your components/pages. This component takes raw markdown, parses it using the `parseMarkdown` function, and then renders it with `<MDCRenderer>`.
171-
172-
```html
173-
<template>
174-
<MDC :value="md" tag="article" />
175-
</template>
176-
177-
<script setup lang="ts">
178-
const md = `
179-
::alert
180-
Hello MDC
181-
::
182-
`
183-
</script>
184-
```
185-
186117
### Prose Components
187118

188119
Prose components are a list of components that will be rendered instead of regular HTML tags. For example, instead of rendering a `<p>` tag, `@nuxtjs/mdc` renders a `<ProseP>` component. This is useful when you want to add extra features to your markdown files. For example, you can add a `copy` button to your code blocks.
@@ -232,11 +163,67 @@ Here is the list of available prose components:
232163
| `em` | `<ProseEm>` | [ProseEm.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseEm.vue) | Emphasis |
233164
| `strong` | `<ProseStrong>` | [ProseStrong.vue](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/components/prose/ProseStrong.vue) | Strong |
234165

166+
## Parsing Markdown
167+
168+
Nuxt MDC exposes a handy helper to parse MDC files. You can import the `parseMarkdown` function from `@nuxtjs/mdc/runtime` and use it to parse markdown files written with MDC syntax.
169+
170+
### Node.js
171+
172+
```ts
173+
// server/api/parse-mdc.ts
174+
import { parseMarkdown } from '@nuxtjs/mdc/runtime'
175+
176+
export default eventHandler(async () => {
177+
const mdc = [
178+
'# Hello MDC',
179+
'',
180+
'::alert',
181+
'This is an Alert',
182+
'::'
183+
].join('\n')
184+
185+
const ast = await parseMarkdown(mdc)
186+
187+
return ast
188+
})
189+
```
190+
191+
### Browser
192+
193+
The `parseMarkdown` function is a universal helper, and you can also use it in the browser, for example inside a Vue component.
194+
195+
```vue
196+
<script setup lang="ts">
197+
import { parseMarkdown } from '@nuxtjs/mdc/runtime'
198+
199+
const ast = await useAsyncData('markdown', () => parseMarkdown('::alert\nMissing markdown input\n::'))
200+
</script>
201+
202+
<template>
203+
<MDCRenderer :body="ast.body" :data="ast.data" />
204+
</template>
205+
```
206+
207+
### Options
208+
209+
The `parseMarkdown` helper also accepts options as the second argument to control the parser's behavior. (Checkout [`MDCParseOptions` interface↗︎](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/types/parser.ts)).
210+
211+
| Name | Default | Description |
212+
| -- | -- | -- |
213+
| `remark.plugins` | `{}` | Register / Configure parser's remark plugins. |
214+
| `rehype.options` | `{}` | Configure `remark-rehype` options. |
215+
| `rehype.plugins` | `{}` | Register / Configure parser's rehype plugins. |
216+
| `highlight` | `false` | Control whether code blocks should highlight or not. You can also provide a custom highlighter. |
217+
| `toc.depth` | `2` | Maximum heading depth to include in the table of contents. |
218+
| `toc.searchDepth` | `2` | Maximum depth of nested tags to search for heading. |
219+
220+
Checkout [`MDCParseOptions` types↗︎](https://github.com/nuxt-modules/mdc/blob/main/src/runtime/types/parser.ts).
221+
235222
## Configurations
236223

237224
You can configure the module by providing the `mdc` property in your `nuxt.config.js`; here are the default options:
238225

239-
```ts [nuxt.config.js]
226+
```ts
240227
import { defineNuxtConfig } from 'nuxt/config'
241228

242229
export default defineNuxtConfig({

0 commit comments

Comments
 (0)