docs: more improvements

Author: atinux

docs/app/components/PreviewCard.vue

@@ -9,8 +9,7 @@ defineProps({
 
 <template>
   <div
-    class="p-4 border rounded-b-md border-[--ui-color-neutral-200] dark:border-[--ui-color-neutral-700] bg-[--ui-color-neutral-50] dark:bg-[--ui-color-neutral-800] dark:text-white"
-    :class="prose ? 'prose' : 'not-prose'"
+    class="px-4 py-1 border rounded-b-md border-[var(--ui-color-neutral-200)] dark:border-[var(--ui-color-neutral-700)] bg-[var(--ui-color-neutral-50)] dark:bg-[var(--ui-color-neutral-800)] dark:text-white"
   >
     <slot />
   </div>

docs/app/components/example/ExampleHero.vue

@@ -1,7 +1,7 @@
 <template>
-  <section>
+  <section class="pt-4">
     <h1 class="text-4xl">
-      <slot />
+      <MDCSlot unwrap="p" />
     </h1>
     <slot name="description" />
   </section>

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

@@ -64,13 +64,13 @@ We created the MDC syntax to supercharge Markdown and give you the ability to in
 Install the [MDC VS Code extension](https://marketplace.visualstudio.com/items?itemName=Nuxt.mdc) to get proper syntax highlighting for your MDC components.
 ::
 
-### Front-matter
+## Front-matter
 
 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 store any information that you would need.
 
-#### Syntax
+### Syntax
 
 You can declare a front-matter block at the top of the Markdown files in the `content/` directory with the `---` identifier.
 
@@ -83,23 +83,93 @@ description: 'meta description of the page'
 <!-- Content of the page -->
 ```
 
-#### Native parameters
+### Native parameters
 
 | Key                                         |   Type    | Default                               | Description                                                                                              |
 | ------------------------------------------- | :-------: | ------------------------------------- | -------------------------------------------------------------------------------------------------------- |
 | `title`                                     | `string`  | First `<h1>`{lang="html"} of the page | Title of the page, will also be injected in metas                                                        |
 | `description`                               | `string`  | First `<p>`{lang="html"} of the page  | Description of the page, will be shown below the title and injected into the metas                       |
-| `navigation`                                | `boolean` | `true`                                | Define if the page is included in [`queryCollectionNavigation`](/docs/utils/query-collection-navigation) return value. |
+| `navigation`                                | `boolean` | `true`                                | Define if the page is included in [`queryCollectionNavigation`](/docs/usage/navigation) return value. |
 
-### Vue Components
 
-Every Vue component created inside the `components/content/` directory will be available in Markdown files.
+## Excerpt
+
+Content excerpt or summary can be extracted from the content using `<!--more-->` as a divider.
+
+```md [content/index.md]
+---
+title: Introduction
+---
+
+Learn how to use `@nuxt/content`.
+
+<!--more-->
+
+Full amount of content beyond the more divider.
+```
+
+Description property will contain the excerpt content unless defined within the Front Matter props.
+
+If there is no `<!--more-->` divider in the text then excerpt is undefined.
+
+Example variables will be injected into the document:
+
+```json
+{
+  "excerpt": Object
+  "body": Object
+  // ... other keys
+}
+```
+
+## Code Highlighting
+
+Nuxt Content uses [Shiki](https://github.com/shikijs/shiki), that colors tokens with VSCode themes.
+
+Code highlighting works both on [`ProsePre`](/docs/components/prose#prosepre) and [`ProseCode`](/docs/components/prose#prosecodeinline).
+
+Each line of a code block gets its line number in the `line` attribute so lines can be labeled or individually styled.
+
+::callout
+[Read the API reference to configure or entirely disable syntax highlighting.](/get-started/configuration)
+::
+
+## Images
+
+You can add images to your `public` directory:
+
+```bash [Directory structure]
+content/
+  index.md
+public/
+  image.png
+nuxt.config.ts
+package.json
+```
+
+And then use them in your markdown files in the `content` directory as such:
+
+```md [content/index.md]
+![my image](/image.png)
+```
+
+## Vue Components
+
+You can use any Vue component in your Markdown files.
+
+We have a special syntax to make it easier to use components in your Markdown files.
+
+```mdc [content/index.md]
+::component-name
+Default slot content
+::
+```
 
 ::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.
 ::
 
-#### Block Components
+### Block Components
 
 Block components are components that accept Markdown content or another component as a slot.
 
@@ -133,17 +203,17 @@ In a markdown file, use the component with the **`::`** identifier.
   ::
 ::
 
-#### Slots
+### Slots
 
 A component's slots can accept content or another components.
 
-- The **default** slot renders the top-level content inside the block component.
-- **named** slots use the `#` identifier to render the corresponding content.
+- **Default slot** renders the top-level content inside the block component or with `#default`
+- **Named slots** use the `#` identifier to render the corresponding content.
 
 ::code-group
   ```mdc [index.md]
   ::hero
-  Default slot text
+  My Page Title
 
   #description
   This will be rendered inside the `description` slot.
@@ -153,119 +223,55 @@ A component's slots can accept content or another components.
   ```html [Hero.vue]
   <template>
     <section>
-      <h1 class="text-4xl"><slot /></h1>
-
+      <h1 class="text-4xl">
+        <MDCSlot unwrap="p" />
+      </h1>
       <slot name="description" />
     </section>
   </template>
   ```
 
   ::preview-card{label="Preview"}
     ::example-hero
-    Default slot text
+    My Page Title
+
     #description
     This will be rendered inside the `description` slot.
     ::
   ::
 ::
 
-#### Nesting
+::note
+Read more about the [`<MDCSlot />`](/docs/components/mdc-slot) component.
+::
 
-MDC supports nested components inside slots by indenting them.
+::tip
+You can use Markdown inside your components slots:
 
 ::code-group
   ```mdc [index.md]
-  ::hero
-    :::card
-      A nested card
-      ::::card
-        A super nested card
-      ::::
-    :::
+  ::the-title
+  A [rich text](/) will be **rendered** by the component.
   ::
   ```
-
-  ::preview-card{label="Preview"}
-    ::example-card
-      A nested card
-      ::example-card
-        A super nested card
-      ::
-    ::
-  ::
-::
-
-::note
-You can add more `::::` when nesting components as a visual reminder.
-::
-
-#### 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.
-
-The `unwrap` prop accepts an HTML tag that will be used to unwrap the content, useful when using tags such as title tags (`<h1>
-`{lang="html"}, `<h2>`{lang="html"}, ...) or inline tags (`<button>`{lang="html"}, `<a>`{lang="html"}, ...).
-
-::code-group
-  ```html [TheTitle.vue]
-  <!-- components/content/TheTitle.vue -->
+  ```html [MyTitle.vue]
   <template>
     <h1 class="text-4xl">
-      <MDCSlot :use="$slots.default" unwrap="p" />
+      <MDCSlot unwrap="p" />
     </h1>
   </template>
   ```
 
-  ```mdc [index.md]
-  ::the-title
-  A [rich text](/) will be **rendered** by the component.
-  ::
-  ```
   ::preview-card{label="Preview"}
     ::example-title
     A [rich text](/) will be **rendered** by the component.
     ::
   ::
 
 ::
-
-The `<MDCSlot />` component can act as a named slot with the `use` property:
-
-```html
-<MDCSlot :use="$slots.description" unwrap="p">
-```
-
-#### Inline components
-
-Inline components are components without slots or `<MDCSlot />`.
-
-They can be used with the `:` identifier.
-
-::code-group
-```mdc [index.md]
-# Title
-
-:banner
-```
-
-```html [Banner.vue]
-<template>
-  <aside>
-    This component does not have any children.
-  </aside>
-</template>
-```
 ::
 
-If you want to use an inline component followed by specific characters like `-`, `_` or `:`, you can use a dummy props specifier after it.
-
-```mdc
-:hello{}-world
-```
-
-In this example, `:hello{}` will search for the `<Hello />` component, and `-world` will be plain text.
-
-#### Props
+### Props
 
 There are two ways to pass props to components using MDC.
 
@@ -394,28 +400,14 @@ The YAML method uses the `---` identifier to declare one prop per line, that can
   ::
 ::
 
-#### Span Text
-
-To create inline spans in your text you can use the `[]` identifier.
-
-::code-group
-  ```mdc [Code]
-  Hello [World]{style="background-color: var(--color-primary-500)"}!
-  ```
-
-  ::preview-card{label="Preview"}
-  Hello [World]{style="background-color: var(--color-primary-500)"}!
-  ::
-::
-
-#### Attributes
+### Attributes
 
 Attributes are useful for highlighting and modifying part of paragraph. The syntax is nearly similar to inline components and markdown links syntax.
 
 Possible values ​​are all named attributes, classes with the notation `.class-name` and an ID with `#id-name`.
 
 ::code-group
-  ```mdc [Code]
+  ```mdc [index.md]
   Hello [World]{style="color: green;" .custom-class #custom-id}!
   ```
 
@@ -427,7 +419,7 @@ Possible values ​​are all named attributes, classes with the notation `.clas
 In addition to mdc components and `span`, attribute syntax will work on images, links, inline `code`, **bold** and _italic_ text.
 
 ::code-group
-  ```md [Code]
+  ```md [index.md]
   Attributes work on:
 
   - ![](/favicon.ico){style="display: inline; margin: 0;"} image,
@@ -543,7 +535,7 @@ const mdcVars = ref({ name: 'Maxime'});
 
 ```
 
-### Prose Components
+## Prose Components
 
 In Nuxt Content, the prose represents HTML tags generated by the Markdown syntax, such as heading levels and links.
 
@@ -556,6 +548,6 @@ If you want to customize a Prose component, here are the recommended steps:
 - In your `components/content/` directory, give it the same name.
 - Make it yours 🚀.
 
-::callout
-Read the complete Prose reference in the [Prose Components section](/docs/components/prose).
+::note{to="/docs/components/prose"}
+Read the complete Prose reference in the Prose Components section.
 ::