Docs Theme v0.9.0
Create a beautiful documentation like this website in seconds ✨
Checkout the live example
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'
}]
]
})
Don't forget to install the dependencies of the modules you add in your nuxt.config.js
tailwind.config.js
v0.4.0+
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.
You can add a static/icon.png
file to enable nuxt-pwa and generate a favicon automatically.
Icon should be a square of at least 512x512
You can add a static/preview.png
file to have a social preview image in your metas.
Image should be at least 640×320px (1280×640px for best display).
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'
}
})
As explained in nuxt.config.js section, we use defu.arrayFn
to merge your config. You can override the i18n.locales
array by using a function, or you can pass an array to concat with the default one (which has only the en
locale).
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.
- This will be used to group the documents in the navigation (defaults to
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
)
- Overwrites the title of the page that will be displayed in the left menu (defaults to
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
- The logo of your project, can be an
github
(String
)- The GitHub repository of your project
owner/name
to display the last version, the releases page, the link at the top and theEdit 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+
- The GitHub repository of your project
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
.
- For GitHub Enterprise, in addition to
twitter
(String
)- The Twitter username
@username
you want to link. Example:@nuxt_js
- The Twitter username
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 tomain
if it cannot be detected).
- The default branch for the GitHub repository of your project, used in the
defaultDir
(String
) v0.6.0+- The default dir of your project, used in the
Edit this page on GitHub link
on each page (defaults todocs
. Can be an empty string eg.""
).
- The default dir of your project, used in the
layout
(String
) v0.4.0+- The layout of your documentation (defaults to
default
). Can be changed tosingle
to have a one-page doc.
- The layout of your documentation (defaults to
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 theindexName
:"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 tolanguage
). - Take a look at the @nuxt/content docsearch config for an example.
- 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
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']
- Type:
Example
<alert>
Check out an info alert with a `codeblock` and a [link](/themes/docs)!
</alert>
Result
Check out an info alert with a codeblock
and a link!
<list>
Props
items
- Type:
Array
- Default:
[]
- Type:
type
v0.7.0+- Type:
String
- Default:
'primary'
- Values:
['primary', 'info', 'success', 'warning', 'danger']
- Type:
icon
v0.7.0+- Type:
String
- Can be used to override the default
type
icon, check out the icons available
- Type:
Example
---
items:
- Item1
- Item2
- Item3
---
<list :items="items"></list>
Result
<badge>
v0.5.0+
Example
<badge>v1.2+</badge>
Result
v1.2+<code-group>
This component uses slots
, refer to code-block
below.
<code-block>
Props
label
- Type:
String
required
- Type:
active
- Type:
Boolean
- Default:
false
- Type:
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
- Type:
Example
---
link: https://codesandbox.io/embed/nuxt-content-l164h?hidenavigation=1&theme=dark
---
<code-sandbox :src="link"></code-sandbox>
Result