Skip to content

Latest commit

 

History

History
executable file
·
135 lines (94 loc) · 4.81 KB

2.markdown.md

File metadata and controls

executable file
·
135 lines (94 loc) · 4.81 KB
Raw

Markdown

Nuxt Content uses the Markdown syntax and conventions to provide a rich-text editing experience.

  • Use Markdown to format your content with Prose components.
  • Edit the meta-data of your pages in the front-matter block of your files.

Prose

In Nuxt Content, Prose represents the HTML tags generated by the Markdown syntax, such as title levels and links. A Vue component corresponds to each tag, allowing you to override them if needed.

::alert{type="info"} Read the complete Prose reference in the API section ::

Example

::code-group

Just a paragraph.
<p>Just a paragraph.</p>

::code-block{label="Preview"} Just a paragraph. :: ::

Customizing

If you want to customize a Prose component, here are the recommended steps:

  • Checkout the original component sources.
  • Use the exact same props.
  • In your components/content/ directory, give it the same name.
  • Make it yours 🚀.

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 hold any information that you would need.

Syntax

You can declare a front-matter block at the top of the Markdown files in the content/ directory with the --- identifier.

---
title: 'Title of the page'
description: 'meta description of the page'
---

<!-- Content of the page -->

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
draft boolean false Mark the page as draft (and only display it in development mode).
navigation boolean true Define if the page is included in fetchContentNavigation return value.
head object true Easy access to useContentHead

When used together with <ContentDoc> or the document-driven mode to display the current page, the useContentHead() composable will be used to set the page's metadata.

Excerpt

Content excerpt or summary can be extracted from the content using <!--more--> as a divider.

---
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:

{
  "_id": "content:index.md"
  "excerpt": Object
  "body": Object
  // ... other keys
}

Code Highlighting

Code highlighting allows you to display beautiful code blocks on your website.

Nuxt Content uses Shiki, that colors tokens with VSCode themes.

Code highlighting works both on ProseCode and ProseCodeInline.

Each line of a code block gets its line number in the line attribute so lines can be labeled or individually styled.

::alert{type="info"} Read the API reference to configure or entirely disable syntax highlighting. ::

Images

You can add images to your public directory:

my-project/
  content/
    index.md
  public/
    img/
      image.png
  nuxt.config.ts
  package.json
  tsconfig.json

And then use them in your markdown files in the content directory as such:

![my image](/img/image.png)