Skip to content

Commit

Permalink
docs: apply studio parsing
Browse files Browse the repository at this point in the history
  • Loading branch information
larbish authored Dec 5, 2024
1 parent c3f2b9b commit 9f19423
Show file tree
Hide file tree
Showing 30 changed files with 694 additions and 593 deletions.
7 changes: 4 additions & 3 deletions docs/content/docs/1.getting-started/1.index.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
---
navigation.title: Introduction
navigation:
title: Introduction
title: Nuxt Content v3
description: The powerful Git-based CMS designed specifically for Nuxt developers.
---
Expand Down Expand Up @@ -35,11 +36,11 @@ Benefits include:

The new collections system provides automatic TypeScript types for all your data. Every utility and API is strongly typed based on your collection definitions, ensuring robust type safety throughout development.

### Nuxt Studio Integration :badge[Soon]{color=neutral}
### Nuxt Studio Integration :badge[Soon]{color="neutral"}

[Nuxt Studio](/docs/studio/setup) and v3 are designed to complement each other perfectly.. The [studio module](https://github.com/nuxtlabs/studio-module) is now integrated directly into Nuxt Content, creating an ideal environment where developers can focus on code while team members manage content through an intuitive interface.

:hr
---

We're excited for you to explore these new capabilities. Dive into our documentation to learn more about integrating the module and implementing best practices in your next project.

Expand Down
5 changes: 1 addition & 4 deletions docs/content/docs/1.getting-started/2.installation.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,13 @@
---
title: Installation
description: 'Get started with Nuxt Content v3 in your Nuxt application.'
description: Get started with Nuxt Content v3 in your Nuxt application.
---

### Install the Package

Choose your preferred package manager to install Nuxt Content v3:

::code-group

```bash [pnpm]
pnpm add @nuxt/content@next
```
Expand All @@ -24,7 +23,6 @@ npm install @nuxt/content@next
```bash [bun]
bun add @nuxt/content@next
```

::

### Register the Module
Expand Down Expand Up @@ -97,4 +95,3 @@ useSeoMeta({
::tip{icon="i-lucide-rocket"}
That's it! You've now created your first Nuxt Content page.
::

42 changes: 25 additions & 17 deletions docs/content/docs/1.getting-started/3.configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,7 @@ Nuxt Content read and parse all the available contents at built time. This optio

Configure markdown parser.

#### `toc`

#### `toc`

::code-group
```ts [Default]
Expand All @@ -31,6 +30,7 @@ toc: {
searchDepth: 2
}
```

```ts [Signature]
type Toc = {
depth: number
Expand All @@ -42,6 +42,7 @@ type Toc = {
Control behavior of Table of Contents generation.
Value:
- `depth`: Maximum heading depth to include in the table of contents.
- `searchDepth`: Maximum depth of nested tags to search for heading.
Expand All @@ -65,6 +66,7 @@ export default defineNuxtConfig({
```ts [Default]
remarkPlugins: {}
```

```ts [Signature]
type RemarkPlugins = Record<string, false | MarkdownPlugin>
```
Expand Down Expand Up @@ -102,6 +104,7 @@ export default defineNuxtConfig({
```ts [Default]
rehypePlugins: {}
```

```ts [Signature]
type RehypePlugins = object
```
Expand Down Expand Up @@ -132,17 +135,19 @@ export default defineNuxtConfig({
```ts [Default]
highlight: false
```

```ts [Signature]
type Highlight = false | object
```
::
Nuxt Content uses [Shiki](https://github.com/shikijs/shiki) to provide syntax highlighting for [`ProsePre`](/docs/components/prose#prosepre) and [`ProseCode`](/docs/components/prose#prosecode).
| Option | Type | Description |
| --------- | :------------------------------------------: | :------------------------------------------------------------------------------------------------------------------ |
| `theme` | `ShikiTheme` or `Record<string, ShikiTheme>` | The [color theme](https://github.com/shikijs/shiki/blob/main/docs/themes.md) to use. |
| `langs` | `ShikiLang[]` | The [loaded languages](https://github.com/shikijs/shiki/blob/main/docs/languages.md) available for highlighting. |
| | | |
| ------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Option | Type | Description |
| `theme` | `ShikiTheme` or `Record<string, ShikiTheme>` | The [color theme](https://github.com/shikijs/shiki/blob/main/docs/themes.md) to use. |
| `langs` | `ShikiLang[]` | The [loaded languages](https://github.com/shikijs/shiki/blob/main/docs/languages.md) available for highlighting. |
- `highlight.theme`
Expand Down Expand Up @@ -291,7 +296,7 @@ export default defineNuxtConfig({

### `LibSQL`

If you plan to deploy your application using LibSQL database you need to use `libsql` database adapter.
If you plan to deploy your application using LibSQL database you need to use `libsql` database adapter.

First, make sure to install the `@libsql/client` package:

Expand Down Expand Up @@ -327,31 +332,33 @@ Configure content renderer.
```ts [Default]
{ h2: true, h3: true, h4: true }
```

```ts [Signature]
type AnchorLinks = boolean | Record<'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6', boolean>
```
::
Control anchor link generation, by default it generates anchor links for `h2`, `h3` and `h4` heading
Value:
- `false`: will disable link generation.
- `true`: will enable link generation for all headings.
- `object`: will customize the link generation.
- `h1: boolean`{lang=ts}: Whether render anchor link for `H1` tags or not.
- `h2: boolean`{lang=ts}: Whether render anchor link for `H2` tags or not.
- `h3: boolean`{lang=ts}: Whether render anchor link for `H3` tags or not.
- `h4: boolean`{lang=ts}: Whether render anchor link for `H4` tags or not.
- `h5: boolean`{lang=ts}: Whether render anchor link for `H5` tags or not.
- `h6: boolean`{lang=ts}: Whether render anchor link for `H6` tags or not.
- `h1: boolean`: Whether render anchor link for `H1` tags or not.
- `h2: boolean`: Whether render anchor link for `H2` tags or not.
- `h3: boolean`: Whether render anchor link for `H3` tags or not.
- `h4: boolean`: Whether render anchor link for `H4` tags or not.
- `h5: boolean`: Whether render anchor link for `H5` tags or not.
- `h6: boolean`: Whether render anchor link for `H6` tags or not.
### `alias`
::code-group
```ts [Default]
alias: {}
```
```ts [Signature]
type Alias = Record<string, string>
```
Expand Down Expand Up @@ -383,9 +390,10 @@ watch: {
Configure content hot reload in development.

Value:
- `enabled`{lang=ts}: Enable/Disable hot reload.
- `port`{lang=ts}: Select the port used for the WebSocket server.
- `showURL`{lang=ts}: Toggle URL display in dev server boot message.

- `enabled`: Enable/Disable hot reload.
- `port`: Select the port used for the WebSocket server.
- `showURL`: Toggle URL display in dev server boot message.

::callout
The watcher is a development feature and will not be included in production.
Expand Down
20 changes: 8 additions & 12 deletions docs/content/docs/1.getting-started/4.migration.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,37 +3,35 @@ title: Migration
description: How to migrate from v2 to v3
---

Nuxt Content v3 had been rebuilt from the ground up, resulting in a new library with enhanced capabilities. While we've redesigned concepts and components in a similar way as Content v2, breaking changes are inevitable.
Nuxt Content v3 had been rebuilt from the ground up, resulting in a new library with enhanced capabilities. While we've redesigned concepts and components in a similar way as Content v2, breaking changes are inevitable.

Don't worry, you don't need to modify your content files, We made sure that Content v3 handles content in the same way as Content v2.

## Changes

Here is the list of breaking changes in Content v3:

- `queryContent()`{lang=ts} API is replaced with new `queryCollection()`{lang=ts}
- `queryContent()` API is replaced with new `queryCollection()`
- New API is backed by SQL
- New API search contents within the specific collection
- `fetchContentNavigation()`{lang=ts} API is replaced with new `queryCollectionNavigation()`{lang=ts}
- Surroundings now has its own separate API `queryCollectionItemSurroundings()`{lang=ts}
- `fetchContentNavigation()` API is replaced with new `queryCollectionNavigation()`
- Surroundings now has its own separate API `queryCollectionItemSurroundings()`
- Document driven mode is fully dropped, meaning:
- Markdown files will not convert to Nuxt pages automatically, you need to create pages, see [how](/docs/components/content-renderer#example)
- `useContent()`{lang=ts} composable is removed
- `useContent()` composable is removed
- We simplified rendering components.
- `<ContentDoc>`, `<ContentList>`, `<ContentNavigation>` and `<ContentQuery>` components are dropped in v3.
- `_dir.yml` files are renamed to `.navigation.yml`
- Multi source is dropped in favor of multi collection.
- Document `._path` is now renamed to `.path`
- `searchContent()`{lang=ts} is dropped in favor of new api `queryCollectionSearchSections`
- `searchContent()` is dropped in favor of new api `queryCollectionSearchSections`
- Full text search can easily be done using this API See [Full-Text Search Snippets](/docs/advanced/fulltext-search)
- `useContentHelpers()`{lang=ts} is removed

- `useContentHelpers()` is removed

## Implement Document Driven mode in v3

Implementing document driven mode is Content v3 is quite easy. All you need is to create a catch-all page in Nuxt and fetch contents based on route path.


```vue [pages/[...slug\\].vue]
<script lang="ts" setup>
const route = useRoute()
Expand Down Expand Up @@ -67,7 +65,6 @@ const v2Query = await queryContent(route.path).findOne()
const v3Query = await queryCollection('content').path(route.path).first()
```


```ts [Find contents with custom filter]
// Content v2
const v2Query = await queryContent()
Expand All @@ -79,8 +76,7 @@ const v3Query = await queryCollection('content')
.first()
```


## Convert `queryContent().findSurround()`{lang=ts}
## Convert `queryContent().findSurround()`

Surround now has it's own separate API.

Expand Down
5 changes: 2 additions & 3 deletions docs/content/docs/2.collections/1.collections.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,17 @@
title: Define Content Collections
navigation:
title: Define
description: 'Learn how to define and configure content collections in your Nuxt application.'
description: Learn how to define and configure content collections in your Nuxt application.
---

The Nuxt Content module automatically parses any content files within the `content/` directory located at the root of your Nuxt application. This setup allows you to freely structure the folder to suit your project's needs.
The Nuxt Content module automatically parses any content files within the `content/` directory located at the root of your Nuxt application. This setup allows you to freely structure the folder to suit your project's needs.

For better organization, consider using Content Collections, which let you categorize and manage content more effectively. These collections are defined in a `content.config.ts` file.

::warning
If no `content.config.ts` file is present, all files within the content folder are parsed and imported by default. However, once a config file is added, only files matching the specified path patterns defined in collections will be imported.
::


## What are Content Collections?

Content Collections organize related items within your Nuxt Content project. They provide a structured way to manage your content, making it easier to query, display, and maintain your site's data.
Expand Down
15 changes: 8 additions & 7 deletions docs/content/docs/2.collections/2.types.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ defineCollection({
```

::tip
Use the **page** type if there is a 1-to-1 relationship between content files and pages on your site.
Use the **page** type if there is a 1-to-1 relationship between content files and pages on your site.
::

### Path generation
Expand All @@ -33,16 +33,17 @@ Nuxt Content will automatically generate a path for each file in the collection,

Here are examples of generated paths based on file structure:

| File | Path |
| -------------------------------- | :-------------------- |
| | |
| -------------------------------- | --------------------- |
| File | Path |
| `content/index.md` | `/` |
| `content/about.md` | `/about` |
| `content/blog/index.md` | `/blog` |
| `content/blog/hello.md` | `/blog/hello` |
| `content/1.guide/2.installation` | `/guide/installation` |

::note
You can use the helper [`queryCollection('COLLECTION').path('PATH')`{lang=ts}](/docs/utils/query-collection) to retrieve content by a specific path.
You can use the helper [`queryCollection('COLLECTION').path('PATH')`](/docs/utils/query-collection) to retrieve content by a specific path.
::

### Schema Overrides
Expand All @@ -57,6 +58,7 @@ When you use the **page** type, Nuxt Content generates several standard fields t
- `navigation`: Page navigation configuration (for [queryCollectionNavigation](/docs/utils/query-collection-navigation))

Here is the corresponding schema applied:

```ts
path: z.string(),
title: z.string(),
Expand Down Expand Up @@ -103,14 +105,14 @@ The data type is useful for content that doesn’t directly correspond to a webp
With data collections, you have complete control over the schema, allowing you to define custom structures.

::note
There’s no strict relationship between collection type and file extension. For instance, a **page** collection can use [Markdown](/docs/files/markdown) or [YAML](/docs/files/yaml) or [JSON](/docs/files/json) files, and **data** collections can use any of these formats as well.
There’s no strict relationship between collection type and file extension. For instance, a **page** collection can use [Markdown](/docs/files/markdown) or [YAML](/docs/files/yaml) or [JSON](/docs/files/json) files, and **data** collections can use any of these formats as well.
::

## Ordering Files

For both types, you may want to control the display order in lists. Use numeric prefixes in file and directory names to specify an order. Nuxt Content will use these numbers when ordering content lists.

``` [Directory structure]
```text [Directory structure]
content/
1.frameworks/
1.vue.md
Expand All @@ -125,4 +127,3 @@ content/
::warning
Separate number from file name using `.` character. Using any other separator will not work.
::

5 changes: 3 additions & 2 deletions docs/content/docs/2.collections/3.sources.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ export const collections = {
The `source` property can be defined as either a string (following a glob pattern) or an object, allowing more detailed source configuration for your target directory and files within the content folder.

**Example:**

- `source: '**` includes all files within the content directory and its subdirectories.
- `source: '**/*.md'`includes all `Markdown` files within the content directory and its subdirectories.
- `source: 'docs/**/*.yml'` includes all `YML` files within the `content/docs` and its subdirectories.
Expand All @@ -41,15 +42,15 @@ Glob patterns to exclude content from the import.

This configuration only applied for **page** type with 1-to-1 relationship between content files and pages on your site.

It represents the path prefix (base URL) of the corresponding page on the website.
It represents the path prefix (base URL) of the corresponding page on the website.

### `cwd`

Root directory for content matching.

### `repository`

External source representing a remote git repository URL (e.g., https://github.com/nuxt/content)
External source representing a remote git repository URL (e.g., <https://github.com/nuxt/content>)

### `authToken`

Expand Down
Loading

0 comments on commit 9f19423

Please sign in to comment.