Docs Theme v0.9.0

Getting Started

To get started quickly you can use the create-nuxt-content-docs package.

yarn create nuxt-content-docs <project-name>

# Make sure you have npx installed (npx is shipped by default since NPM 5.2.0) or npm v6.1 or yarn.
npx create-nuxt-content-docs <project-name>

# Starting with npm v6.1 you can do:
npm init nuxt-content-docs <project-name>

It will ask you some questions (name, title, url, repository, etc.), when answered the dependencies will be installed. The next step is to navigate to the project folder and launch it:

cd <project-name>
yarn dev

cd <project-name>
npm run dev

The application is now running on http://localhost:3000. Well done!

Manual Setup

Let's say we're creating the documentation of an open-source project in the docs/ directory.

The theme is a classic NuxtJS app, you need:

package.json

This file can be created with npm init.

Install nuxt and @nuxt/content-theme-docs:

yarn add nuxt @nuxt/content-theme-docs

npm install nuxt @nuxt/content-theme-docs

Example

{
  "name": "docs",
  "version": "1.0.0",
  "scripts": {
    "dev": "nuxt",
    "build": "nuxt build",
    "start": "nuxt start",
    "generate": "nuxt generate"
  },
  "dependencies": {
    "@nuxt/content-theme-docs": "^0.1.3",
    "nuxt": "^2.14.0"
  }
}

nuxt.config.js

Import the theme function from @nuxt/content-theme-docs:

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

export default theme({
  // [additional nuxt configuration]
})

The theme exports a function to setup the nuxt.config.js and allows you to add / override the default config.

Check out the documentation of defu.arrayFn to see how the config is merged.

Example

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

export default theme({
  docs: {
    primaryColor: '#E24F55'
  },
  loading: { color: '#00CD81' },
  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'
  },
  buildModules: [
    ['@nuxtjs/google-analytics', {
      id: 'UA-12301-2'
    }]
  ]
})

tailwind.config.js

You can override the default theme config by creating your own tailwind.config.js.

The theme design is based on a primary color to make it easy to override.

Default colors are generated using theme-colors with docs.primaryColor as base. v0.7.0+

Example

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          // ...
        }
      }
    }
  }
}

content/

This is where you put your markdown content files. You can learn more in the following section.

static/

This is where you put your static assets like the logo.

Example

content/
  en/
    index.md
static/
  icon.png
nuxt.config.js
package.json

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