docs: update structure

Author: larbish

docs/content/docs/1.getting-started/2.installation.md

@@ -52,7 +52,7 @@ export const collections = {
 }
 ```
 
-This configuration creates a default `content` collection that processes all Markdown files in your project. You can customize the collection settings based on your needs.
+This configuration creates a default `content` collection that processes all Markdown files located in the `content` folder of your project. You can customize the collection settings based on your needs.
 
 ::tip
 The `type: page` setting specifies that each file in the collection represents a [Markdown page](/docs/usage/markdown).

…nt/docs/1.getting-started/6.migration.md …nt/docs/1.getting-started/3.migration.mddocs/content/docs/1.getting-started/6.migration.md renamed to docs/content/docs/1.getting-started/3.migration.md docs/content/docs/1.getting-started/6.migration.md renamed to docs/content/docs/1.getting-started/3.migration.md

@@ -1,2 +1,3 @@
-title: Concepts
+
+title: Key Concepts
 icon: i-lucide-lightbulb

…ocs/1.getting-started/5.configuration.md …ocs/1.getting-started/4.configuration.mddocs/content/docs/1.getting-started/5.configuration.md renamed to docs/content/docs/1.getting-started/4.configuration.md docs/content/docs/1.getting-started/5.configuration.md renamed to docs/content/docs/1.getting-started/4.configuration.md

@@ -1,8 +1,15 @@
 ---
-title: 'Content Collections'
+title: Define Collections
 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. For a 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.
@@ -34,8 +41,9 @@ export const collections = {
 }
 ```
 
-::note{to="#collection-types"}
-Learn more about the different types of collections.
+
+::note{to="/usage/types"}
+Learn more about collection types.
 ::
 
 ### Collection Schema
@@ -61,30 +69,13 @@ export const collections = {
 }
 ```
 
-::tip
-`@nuxt/content` exposes a `z` object that contains a set of Zod schemas for common data types.
+::note
+`@nuxt/content` exposes a `z` object that contains a set of Zod schemas for common data types. Check the [Zod’s README](https://github.com/colinhacks/zod) for complete documentation on how Zod works and what features are available.
 ::
 
-### Multiple Collections
-
-You can define multiple collections to organize different types of content:
-
-```ts [content.config.ts]
-import { defineCollection, z } from '@nuxt/content'
-
-export const collections = {
-  blog: defineCollection({
-    // Load top-level Markdown files from content/blog
-    source: 'blog/*.md',
-    type: 'page'
-  }),
-  docs: defineCollection({
-    // Load all Markdown files from content/docs
-    source: 'docs/**.md',
-    type: 'page'
-  })
-}
-```
+::tip
+You can define as many collections as you want to organize different types of content.
+::
 
 ## Querying Collections
 
@@ -141,12 +132,6 @@ type CollectionSource = {
 }
 ```
 
-### Collection Types
-
-The `type` parameter determines content processing:
-- `data`: For structured data files (JSON, YAML) that don't require rendering
-- `page`: For full pages with layouts and components that need rendering
-
 ### Built-in Fields
 
 Every collection includes these default fields:

docs/content/docs/2.usage/.navigation.yml

@@ -0,0 +1,112 @@
+---
+title: Collection types
+description: Learn about the two types of collections you can define in Nuxt Content.
+---
+
+In Nuxt Content, you can specify a type for each collection, depending on the intended purpose of the collection files. Collections can be defined as either **page** or **data** types.
+
+## Page type
+
+```ts
+defineCollection({
+  source: '**.md',
+  type: 'page'
+})
+```
+
+Use the **page** type if there is a 1-to-1 relationship between content files and pages on your site. 
+
+### Path generation
+
+Nuxt Content will automatically generate a path for each file in the collection, making it easy to create URL mappings.
+
+Here are examples of generated paths based on file structure:
+
+| 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` |
+
+
+You can use the helper [`queryCollection('COLLECTION').path('PATH')`{lang=ts}](/composables/query-collection) to retrieve content by a specific path.
+
+### Schema Overrides
+
+When you use the **page** type, Nuxt Content generates several standard fields that are commonly used for web pages. These fields provide structure and are **automatically** applied to the collection’s schema:
+```ts
+  // Generated path of your file
+  path: z.string(),
+  // Title of your page
+  title: z.string(),
+  // Description of your page
+  description: z.string(),
+  // Seo information
+  seo: z.intersection(
+    z.object({
+      title: z.string().optional(),
+      description: z.string().optional(),
+      meta: z.array(z.record(z.string(), z.any())).optional(),
+      link: z.array(z.record(z.string(), z.any())).optional(),
+    }),
+    z.record(z.string(), z.any()),
+  ).optional().default({}),
+  // AST of your markdown parsed (only useful for Markdown files)
+  body: z.object({
+    type: z.string(),
+    children: z.any(),
+    toc: z.any(),
+  }),
+  // Navigation information
+  navigation: z.union([
+    z.boolean(),
+    z.object({
+      title: z.string(),
+      description: z.string(),
+      icon: z.string(),
+    }),
+  ]).default(true),
+```
+
+::note
+You can override any of these fields by defining them in the collection’s schema.
+::
+
+### Ordering Files
+
+Since each file corresponds to a page, 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]
+content/
+  1.frameworks/
+    1.vue.md
+    2.nuxt.md
+  2.examples/
+    1.vercel.md
+    2.netlify.md
+    3.heroku.md
+    index.md
+```
+
+::warning
+Separate number from file name using `.` character. Using any other separator will not work.
+::
+
+## Data type
+
+```ts
+defineCollection({
+  source: 'authors/**.yml',
+  type: 'data'
+})
+```
+
+The data type is useful for content that doesn’t directly correspond to a webpage but instead represents structured data you might want to query and display within your application.
+
+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](/usage/markdown) or [YAML](/usage/yaml) or JS[Markdown](/usage/json) files, and **data** collections can use any of these formats as well. 
+::

…/docs/1.getting-started/3.collections.md …cs/content/docs/2.usage/1.collections.mddocs/content/docs/1.getting-started/3.collections.md renamed to docs/content/docs/2.usage/1.collections.md docs/content/docs/1.getting-started/3.collections.md renamed to docs/content/docs/2.usage/1.collections.md

@@ -3,7 +3,6 @@ title: Markdown Pages
 description: "Nuxt Content uses the Markdown syntax and conventions to provide a rich-text editing experience."
 ---
 
-
 ## Define Collection
 
 ```ts [content.config.ts]
@@ -16,12 +15,11 @@ export const collections = {
     })
   })
 }
-
 ```
 
 ## Create `.md` files
 
-Create authors files in `content/blog/` directory.
+Create blog posts in `content/blog/` directory.
 
 ::code-group
 ```md [foo.md]
@@ -48,19 +46,19 @@ Now we can query blog posts:
 
 ```ts
 // Find a foo post
-const theAuthor = await queryCollection('blog')
+const fooPost = await queryCollection('blog')
   .path('/foo')
   .first()
 
 // Get all posts
-const post = await queryCollection('blog')
+const allPosts = await queryCollection('blog')
   .order('date', 'DESC')
   .all()
 ```
 
 ## MDC Syntax
 
-We created the MDC syntax to supercharge Markdown and give you the ability to leverage the power of Vue components with slots and props.
+We created the MDC syntax to supercharge Markdown and give you the ability to integrate Vue components with slots and props inside your Markdown.
 
 ::callout
 Install the [MDC VS Code extension](https://marketplace.visualstudio.com/items?itemName=Nuxt.mdc) to get proper syntax highlighting for your MDC components.
@@ -70,7 +68,7 @@ Install the [MDC VS Code extension](https://marketplace.visualstudio.com/items?i
 
 Front-matter is a convention of Markdown-based CMS to provide meta-data to pages, like description or title. In Nuxt Content, the front-matter uses the YAML syntax with `key: value` pairs.
 
-These data are available when rendering the content and can hold any information that you would need.
+These data are available when rendering the content and can store any information that you would need.
 
 #### Syntax
 
@@ -159,7 +157,7 @@ And then use them in your markdown files in the `content` directory as such:
 
 Every Vue component created inside the `components/content/` directory will be available in Markdown files.
 
-::callout{ type="info"}
+::warning
 Components that are used in Markdown has to be marked as `global` in your Nuxt app if you don't use the `components/content/` directory, visit [Nuxt 3 docs](https://nuxt.com/docs/guide/directory-structure/components) to learn more about it.
 ::
 
@@ -195,10 +193,9 @@ In a markdown file, use the component with the **`::`** identifier.
     The content of the card
     ::
   ::
-
 ::
 
-##### Slots
+#### Slots
 
 A component's slots can accept content or another components.
 
@@ -234,7 +231,7 @@ A component's slots can accept content or another components.
   ::
 ::
 
-##### Nesting
+#### Nesting
 
 MDC supports nested components inside slots by indenting them.
 
@@ -243,9 +240,9 @@ MDC supports nested components inside slots by indenting them.
   ::hero
     :::card
       A nested card
-      ::card
+      ::::card
         A super nested card
-      ::
+      ::::
     :::
   ::
   ```
@@ -260,11 +257,11 @@ MDC supports nested components inside slots by indenting them.
   ::
 ::
 
-::callout{type="info"}
+::note
 You can add more `::::` when nesting components as a visual reminder.
 ::
 
-##### Markdown rendering
+#### Markdown rendering
 
 The `<MDCSlot />`{lang="html"} component is auto-imported by Nuxt Content. It acts as a special slot that accepts rich text rendered by Markdown.
 
@@ -334,7 +331,7 @@ In this example, `:hello{}` will search for the `<Hello />` component, and `-wor
 
 There are two ways to pass props to components using MDC.
 
-##### Inline method
+#### Inline method
 
 The `{}` identifier passes props to components in a terse way by using a `key=value` syntax.
 
@@ -404,7 +401,7 @@ Note that in this case you should use single quotes for the value string so you
 ```
 ::
 
-##### YAML method
+#### YAML method
 
 The YAML method uses the `---` identifier to declare one prop per line, that can be useful for readability.
 

docs/content/docs/2.usage/1.source.md

@@ -0,0 +1,2 @@
+icon: i-lucide-code-xml
+title: Advanced Concepts