docs: more improvements

nuxt · Nov 8, 2024 · 705d63e · 705d63e
1 parent a0099fd
commit 705d63e
Show file tree

Hide file tree

Showing 7 changed files with 238 additions and 200 deletions.
diff --git a/docs/app/components/PreviewCard.vue b/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>

diff --git a/docs/app/components/example/ExampleHero.vue b/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>

diff --git a/docs/content/docs/3.files/1.markdown.md b/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.
 ::