Skip to content

Commit f7b51d8

Browse files
atinuxatinux
committed
docs: improve markdown content
1 parent b9c29d5 commit f7b51d8

File tree

2 files changed

+125
-84
lines changed

2 files changed

+125
-84
lines changed

‎docs/content/docs/3.files/1.markdown.md‎

Lines changed: 113 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
---
22
title: Markdown
3-
description: "Nuxt Content uses the Markdown syntax and conventions to provide a rich-text editing experience."
3+
description: "Create and query Markdown files in your Nuxt applications and use the MDC syntax to integrate Vue components."
44
---
55

6-
## Define Collection
6+
## Usage
7+
8+
### Define a Collection
79

810
```ts [content.config.ts]
911
export const collections = {
@@ -17,7 +19,11 @@ export const collections = {
1719
}
1820
```
1921

20-
## Create `.md` files
22+
::note{to="/docs/collections/types#page-type"}
23+
Learn more about the `page` collection type.
24+
::
25+
26+
### Create `.md` files
2127

2228
Create blog posts in `content/blog/` directory.
2329

@@ -26,8 +32,10 @@ Create blog posts in `content/blog/` directory.
2632
---
2733
date: 2020-11-11
2834
---
29-
Hello,
30-
This is Foo here.
35+
36+
# Foo
37+
38+
This is Foo blog post.
3139
```
3240

3341

@@ -40,28 +48,38 @@ I am bar. Nice to meet you.
4048
```
4149
::
4250

43-
## Query Data
51+
### Query Markdown Files
4452

4553
Now we can query blog posts:
4654

4755
```ts
48-
// Find a foo post
49-
const fooPost = await queryCollection('blog')
50-
.path('/foo')
51-
.first()
52-
53-
// Get all posts
54-
const allPosts = await queryCollection('blog')
55-
.order('date', 'DESC')
56-
.all()
56+
// Get the foo post
57+
const fooPost = await queryCollection('blog').path('/foo').first()
58+
59+
// Find all posts
60+
const allPosts = await queryCollection('blog').order('date', 'DESC').all()
5761
```
5862

59-
## MDC Syntax
63+
### Display Markdown
6064

61-
We created the MDC syntax to supercharge Markdown and give you the ability to integrate Vue components with slots and props inside your Markdown.
65+
To display the content of a markdown file, you can use the [`<ContentRenderer>`](/docs/components/content-renderer) component.
6266

63-
::callout
64-
Install the [MDC VS Code extension](https://marketplace.visualstudio.com/items?itemName=Nuxt.mdc) to get proper syntax highlighting for your MDC components.
67+
```vue [blog/[slug\\].vue]
68+
<script setup>
69+
const slug = useRoute().params.slug
70+
const { data: post } = await useAsyncData(`blog-${slug}`, () => {
71+
return queryCollection('blog').path(slug).first()
72+
})
73+
</script>
74+
75+
<template>
76+
<!-- Render the blog post as Prose & Vue components -->
77+
<ContentRenderer :value="post" />
78+
</template>
79+
```
80+
81+
::note
82+
Read more about the [`<ContentRenderer>`](/docs/components/content-renderer) component and [`Prose Components`](/docs/components/prose).
6583
::
6684

6785
## Front-matter
@@ -83,6 +101,17 @@ description: 'meta description of the page'
83101
<!-- Content of the page -->
84102
```
85103

104+
```ts [example.ts]
105+
const home = await queryCollection('content').path('/').first()
106+
107+
console.log(home.title)
108+
// => 'Title of the page'
109+
console.log(home.description)
110+
// => 'meta description of the page'
111+
console.log(home.body)
112+
// => AST object of the page content
113+
```
114+
86115
### Native parameters
87116

88117
| Key | Type | Default | Description |
@@ -91,68 +120,14 @@ description: 'meta description of the page'
91120
| `description` | `string` | First `<p>`{lang="html"} of the page | Description of the page, will be shown below the title and injected into the metas |
92121
| `navigation` | `boolean` | `true` | Define if the page is included in [`queryCollectionNavigation`](/docs/utils/query-collection-navigation) return value. |
93122

123+
## MDC Syntax
94124

95-
## Excerpt
96-
97-
Content excerpt or summary can be extracted from the content using `<!--more-->` as a divider.
98-
99-
```md [content/index.md]
100-
---
101-
title: Introduction
102-
---
103-
104-
Learn how to use `@nuxt/content`.
105-
106-
<!--more-->
107-
108-
Full amount of content beyond the more divider.
109-
```
110-
111-
Description property will contain the excerpt content unless defined within the Front Matter props.
112-
113-
If there is no `<!--more-->` divider in the text then excerpt is undefined.
114-
115-
Example variables will be injected into the document:
116-
117-
```json
118-
{
119-
"excerpt": Object
120-
"body": Object
121-
// ... other keys
122-
}
123-
```
124-
125-
## Code Highlighting
126-
127-
Nuxt Content uses [Shiki](https://github.com/shikijs/shiki), that colors tokens with VSCode themes.
128-
129-
Code highlighting works both on [`ProsePre`](/docs/components/prose#prosepre) and [`ProseCode`](/docs/components/prose#prosecodeinline).
130-
131-
Each line of a code block gets its line number in the `line` attribute so lines can be labeled or individually styled.
125+
We created the MDC syntax to supercharge Markdown and give you the ability to integrate Vue components with slots and props inside your Markdown.
132126

133-
::callout
134-
[Read the API reference to configure or entirely disable syntax highlighting.](/docs/getting-started/configuration)
127+
::callout{icon="i-simple-icons-visualstudiocode" to="https://marketplace.visualstudio.com/items?itemName=Nuxt.mdc"}
128+
Install the **MDC VS Code extension** to get proper syntax highlighting for the MDC syntax.
135129
::
136130

137-
## Images
138-
139-
You can add images to your `public` directory:
140-
141-
```bash [Directory structure]
142-
content/
143-
index.md
144-
public/
145-
image.png
146-
nuxt.config.ts
147-
package.json
148-
```
149-
150-
And then use them in your markdown files in the `content` directory as such:
151-
152-
```md [content/index.md]
153-
![my image](/image.png)
154-
```
155-
156131
## Vue Components
157132

158133
You can use any Vue component in your Markdown files.
@@ -551,3 +526,64 @@ If you want to customize a Prose component, here are the recommended steps:
551526
::note{to="/docs/components/prose"}
552527
Read the complete Prose reference in the Prose Components section.
553528
::
529+
530+
## Code Highlighting
531+
532+
Nuxt Content uses [Shiki](https://github.com/shikijs/shiki), that colors tokens with VSCode themes.
533+
534+
Code highlighting works both on [`ProsePre`](/docs/components/prose#prosepre) and [`ProseCode`](/docs/components/prose#prosecodeinline).
535+
536+
Each line of a code block gets its line number in the `line` attribute so lines can be labeled or individually styled.
537+
538+
::callout
539+
[Read the API reference to configure or entirely disable syntax highlighting.](/docs/getting-started/configuration)
540+
::
541+
542+
## Images
543+
544+
You can add images to your `public` directory:
545+
546+
```bash [Directory structure]
547+
content/
548+
index.md
549+
public/
550+
image.png
551+
nuxt.config.ts
552+
package.json
553+
```
554+
555+
And then use them in your markdown files in the `content` directory as such:
556+
557+
```md [content/index.md]
558+
![my image](/image.png)
559+
```
560+
561+
## Excerpt
562+
563+
Content excerpt or summary can be extracted from the content using `<!--more-->` as a divider.
564+
565+
```md [content/index.md]
566+
---
567+
title: Introduction
568+
---
569+
570+
Learn how to use `@nuxt/content`.
571+
572+
<!--more-->
573+
574+
Full amount of content beyond the more divider.
575+
```
576+
577+
Description property will contain the excerpt content unless defined within the Front Matter props.
578+
579+
If there is no `<!--more-->` divider in the text then excerpt is undefined.
580+
581+
Example variables will be injected into the document:
582+
583+
```json
584+
{
585+
"excerpt": Object
586+
"body": Object
587+
// ... other keys
588+
}
589+
```

‎docs/content/docs/3.utils/1.query-collection.md‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,13 @@ title: queryCollection
33
description: 'The queryCollection composable provides methods for querying and fetching your collections.'
44
---
55

6-
## Type
7-
8-
```ts
9-
function queryCollection<T extends keyof Collections>(collection: T): CollectionQueryBuilder<Collections[T]>
10-
```
11-
126
## Usage
137

14-
Use the auto-imported `queryCollection` to find contents inside a collection.Here we assume that you havr defined `docs` collection inside `content.config.ts`. If you have not defined any collection, check [How to define a collection](/docs/collections/collections#defining-collections).
8+
Use the auto-imported `queryCollection` to find contents inside a collection.Here we assume that you havr defined `docs` collection inside `content.config.ts`.
9+
10+
::note
11+
If you have not defined any collection, check [How to define a collection](/docs/collections/collections#defining-collections).
12+
::
1513

1614
```vue [pages/[...slug\\].vue]
1715
<script>
@@ -24,6 +22,13 @@ const { data: page } = await useAsyncData(route.path, () => {
2422

2523
## API
2624

25+
### Type
26+
27+
```ts
28+
function queryCollection<T extends keyof Collections>(collection: T): CollectionQueryBuilder<Collections[T]>
29+
```
30+
31+
2732
### `queryCollection(collection: CollectionName)`
2833

2934
Create a query builder to search in the specific collection.

0 commit comments

Comments
 (0)