Docs Theme

Content

Once you've setup your documentation, you can directly start writing your content.

Check out the documentation on writing markdown content

Locales

The first level of directories in the content/ folder are the locales used with nuxt-i18n defined in your nuxt.config.js. By default there is only the default en locale defined, you have to create a content/en/ directory to make it work.

You can override the locales in your nuxt.config.js:

import theme from '@nuxt/content-theme-docs'

export default theme({
  i18n: {
    locales: () => [{
      code: 'fr',
      iso: 'fr-FR',
      file: 'fr-FR.js',
      name: 'Français'
    }, {
      code: 'en',
      iso: 'en-US',
      file: 'en-US.js',
      name: 'English'
    }],
    defaultLocale: 'en'
  }
})

Routing

Each markdown page in the content/{locale}/ directory will become a page and will be listed in the left navigation.

You can also put your markdown files in subdirectories to generate sub-routes. v0.4.0+

Example

content/
  en/
    examples/
      basic-usage.md
    setup.md

Result

/examples/basic-usage
/setup

You can take a look at our docs content folder to have an example

Front-matter

To make it work properly, make sure to include these properties in the front-matter section of your markdown files.

Required fields

• title (String)
  • The title of the page will be injected in metas
• description (String)
  • The description of the page will be injected in metas
• position (Number)
  • This will be used to sort the documents in the navigation

Optional fields

• category (String)
  • This will be used to group the documents in the navigation (defaults to "")
  • If category is falsy or not a string, it is coerced to be an empty string, and isn't renderd in the sidebar.
• version (Float)
  • Alert users that the page is new with a badge. Once the page is seen, the version is stored in the local storage until you increment it
• fullscreen (Boolean)
  • Grows the page and hides the table of contents
• menuTitle (String) v0.4.0+
  • Overwrites the title of the page that will be displayed in the left menu (defaults to title)
• subtitle (String) v0.5.0+
  • Adds a subtitle under the page title
• badge (String) v0.5.0+
  • Adds a badge next to the page title

Example

---
title: 'Introduction'
description: 'Empower your NuxtJS application with this awesome module.'
position: 1
category: 'Getting started'
version: 1.4
fullscreen: false
menuTitle: 'Intro'
---

Introducing my awesome Nuxt module!

Settings

You can create a content/settings.json file to configure the theme.

Properties

• title (String)
  • The title of your documentation
• url (String)
  • The url where your documentation will be deployed
• logo (String | Object)
  • The logo of your project, can be an Object to set a logo per color mode
• github (String)
  • The GitHub repository of your project owner/name to display the last version, the releases page, the link at the top and the Edit this page on GitHub link on each page Example: nuxt/content.
  • For GitHub Enterprise, you have to assign a full url of your project without a trailing slash. Example: https://hostname/repos/owner/name. v0.6.0+
• githubApi (String) v0.6.0+
  • For GitHub Enterprise, in addition to github, you have to assign a API full url of your project without a trailing slash. Example: https://hostname/api/v3/repos/owner/name.
  • Releases are fetched from ${githubApi}/releases.
• twitter (String)
  • The Twitter username @username you want to link. Example: @nuxt_js
• defaultBranch (String) v0.2.0+
  • The default branch for the GitHub repository of your project, used in the Edit this page on GitHub link on each page (defaults to main if it cannot be detected).
• defaultDir (String) v0.6.0+
  • The default dir of your project, used in the Edit this page on GitHub link on each page (defaults to docs. Can be an empty string eg. "").
• layout (String) v0.4.0+
  • The layout of your documentation (defaults to default). Can be changed to single to have a one-page doc.
• algolia (Object) v0.7.0+
  • This option allows you to use Algolia DocSearch to replace the simple built-in search. In order to enable it, you need to provide at least the apiKey and the indexName:

    "algolia": {
        "apiKey": "<API_KEY>",
        "indexName": "<INDEX_NAME>",
        "langAttribute": "language"
    }
    

  • If you use i18n, make sure the <langAttribute> is the same as the html lang selector in the config (defaults to language).
  • Take a look at the @nuxt/content docsearch config for an example.

Example

{
  "title": "Nuxt Content",
  "url": "https://content.nuxtjs.org",
  "logo": {
    "light": "/logo-light.svg",
    "dark": "/logo-dark.svg"
  },
  "github": "nuxt/content",
  "twitter": "@nuxt_js"
}

Images

You can apply dark-img and light-img classes to your images when you have two versions to automatically swap dependending on the color mode.

Example

<img src="/logo-light.svg" class="light-img" alt="Logo light" />
<img src="/logo-dark.svg" class="dark-img" alt="Logo dark" />

Result

Try switching between light and dark mode: 

Components

The theme comes with some default Vue.js components you can use directly in your markdown content.

You can create your own components in the components/global/ folder, check out this section. v0.3.0+

<alert>

Props

• type
  • Type: String
  • Default: 'info'
  • Values: ['info', 'success', 'warning', 'danger']

Example

<alert>

Check out an info alert with a `codeblock` and a [link](/themes/docs)!

</alert>

Result

<list>

Props

• items
  • Type: Array
  • Default: []
• type v0.7.0+
  • Type: String
  • Default: 'primary'
  • Values: ['primary', 'info', 'success', 'warning', 'danger']
• icon v0.7.0+
  • Type: String
  • Can be used to override the default type icon, check out the icons available

Example

---
items:
  - Item1
  - Item2
  - Item3
---

<list :items="items"></list>

Result

<badge>

Example

<badge>v1.2+</badge>

Result

<code-group>

This component uses slots, refer to code-block below.

<code-block>

Props

• label
  • Type: String
  • required
• active
  • Type: Boolean
  • Default: false

Example

# Backslashes are for demonstration

<code-group>
  <code-block label="Yarn" active>

  ```bash
  yarn add @nuxt/content-theme-docs
  \```

  </code-block>
  <code-block label="NPM">

  ```bash
  npm install @nuxt/content-theme-docs
  \```

  </code-block>
</code-group>

Result

yarn add @nuxt/content-theme-docs

npm install @nuxt/content-theme-docs

<code-sandbox>

Props

• src
  • Type: String
  • required

Example

---
link: https://codesandbox.io/embed/nuxt-content-l164h?hidenavigation=1&theme=dark
---

<code-sandbox :src="link"></code-sandbox>

Result

Showcases