Skip to content

Latest commit

 

History

History
433 lines (330 loc) · 12.7 KB

3.configuration.md

File metadata and controls

433 lines (330 loc) · 12.7 KB
Raw
icon
heroicons-outline:adjustments

Configuration

You can configure Nuxt Content with the content property in your nuxt.config.js|ts file.

export default defineNuxtConfig({
  content: {
    // My custom configuration
  }
})

api

  • Type: Record<String, any>{lang=ts}
  • Default: { baseURL: '/api/_content' }{lang=ts}

Change default behaviour of Content APIs.

  • baseURL{lang=ts}: change the base URL of Content APIs. Default is /api/_content.
export default defineNuxtConfig({
  content: {
    api: {
      baseURL: '/api/_my_content'
    }
  }
})

watch

  • Type: Object | false{lang=ts}
  • Default: { port: 4000, showUrl: true }{lang=ts}

Disable content watcher and hot content reload.

The watcher is a development feature and will not be included in production.

::code-group

export default defineNuxtConfig({
  content: {
    watch: {
      ws: {
        port: 4000,
        showUrl: true
      }
    }
  }
})
export default defineNuxtConfig({
  content: {
    watch: false
  }
})

::

ws options

Option Default Description
port 4000 Select the port used for the WebSocket server.
showUrl false Toggle URL display in dev server boot message.

sources

  • Type: Record<String, Object>{lang=ts}
  • Default: {}{lang=ts}

Define different sources for contents.

Contents can be located in multiple places, in multiple directories, or in remote git repositories thanks to unstorage.

export default defineNuxtConfig({
  content: {
    sources: {
      // overwrite default source AKA `content` directory
      content: {
        driver: 'fs',
        prefix: '/docs', // All contents inside this source will be prefixed with `/docs`
        base: resolve(__dirname, 'content')
      }
      // Additional sources
      fa: {
        prefix: '/fa', // All contents inside this source will be prefixed with `/fa`
        driver: 'fs',
        // ...driverOptions
        base: resolve(__dirname, 'content-fa') // Path for source directory
      },
      github: {
        prefix: '/blog', // Prefix for routes used to query contents
        driver: 'github', // Driver used to fetch contents (view unstorage documentation)
        repo: "<owner>/<repo>",
        branch: "main",
        dir: "content", // Directory where contents are located. It could be a subdirectory of the repository.
        // Imagine you have a blog inside your content folder. You can set this option to `content/blog` with the prefix option to `/blog` to avoid conflicts with local files.
      },
    }
  }
})

::alert{type="info"} It is highly recommended to prevent modifying default source. If you want to load contents from another location, consider adding an additional source. ::

ignores

  • Type: string[] | object[]{lang=ts}
  • Default: ['\\.', '-']{lang=ts}

List of ignore patterns to exclude content from parsing, rendering and watching.

Note that under the hood:

  • paths are managed by unstorage, so you will need to use : in place of /
  • patterns are converted to Regular Expressions, so you will need to escape appropriately
  • patterns are actually prefixes; use a match-all pattern to negate this (see final example)
export default defineNuxtConfig({
  content: {
    ignores: [
      'hidden',        // any file or folder prefixed with the word "hidden"
      'hidden:',       // any folder that exactly matches the word "hidden"
      'path:to:file',  // any file path matching "/path/to/file"
      '.+\\.bak$',     // any file with the extension ".bak"
    ]
  }
})

From version 2.7 ignores will support a more flexible, idiomatic format.

You can use this from version 2.6 using the experimental.advancedIgnoresPattern flag:

export default defineNuxtConfig({
  content: {
    experimental: {
      advancedIgnoresPattern: true
    },
    ignores: [
      'hidden',        // any file or folder that contains the word "hidden"
      '/hidden/',      // any folder that exactly matches the word "hidden"
      '/path/to/file', // any file path matching "/path/to/file"
      '\\.bak$',       // any file with the extension ".bak"
    ]
  }
})

markdown

This module uses remark and rehype under the hood to compile markdown files into JSON AST that will be stored into the body variable.

To configure how the module will parse Markdown, you can use markdown.remarkPlugins and markdown.rehypePlugins in your nuxt.config.ts file:

export default defineNuxtConfig({
  content: {
    markdown: {

      // Object syntax can be used to override default options
      remarkPlugins: {
        // Override remark-emoji options
        'remark-emoji': {
          emoticon: true
        },

        // Disable remark-gfm
        'remark-gfm': false,

        // Add remark-oembed
        'remark-oembed': {
          // Options
        }
      },

      // Array syntax can be used to add plugins
      rehypePlugins: [
        'rehype-figure'
      ]
    }
  }
})

Here is a list of plugins @nuxt/content is using by default.

::alert{type="info"} When adding a new plugin, make sure to install it in your dependencies. ::

mdc

  • Type: Boolean{lang=ts}
  • Default: true{lang=ts}

Whether MDC syntax should be supported or not.

toc

  • Type: Object{lang=ts}
  • Default: { depth: 2, searchDepth: 2 }{lang="ts"}

Control behavior of Table of Contents generation.

  • depth{lang=ts}: Maximum heading depth to include in the table of contents.
  • searchDepth{lang=ts}: Maximum depth of nested tags to search for heading.

tags

  • Type: Object{lang=ts}

Tags will be used to replace markdown components and render custom components instead of default ones.

export default defineNuxtConfig({
  content: {
    markdown: {
      tags: {
        p: 'MyCustomParagraph'
      }
    }
  }
})

anchorLinks

  • Type: Boolean | Object{lang=ts}
  • Default: {depth: 4, exclude: [1]}{lang=ts}

By default, the Content module generates anchor links for h2, h3 and h4 headings. Using this option, you can control link generation.

false{lang=ts} will disable link generation.

true{lang=ts} will enable link generation for all headings.

anchorLinks options

Option Type Description
depth number Sets the maximal depth for anchor link generation.
exclude number[] A list of headings to exclude from link generation.

highlight

  • Type: false | Object{lang=ts}

Nuxt Content uses Shiki to provide syntax highlighting for ProseCode and ProseCodeInline.

highlight options

Option Type Description
theme ShikiTheme or Record<string, ShikiTheme> The color theme to use.
preload ShikiLang[] The preloaded languages available for highlighting.

highlight.theme

Theme can be specified by a single string but also supports an object with multiple themes.

This option is compatible with Color Mode module.

If you are using multiple themes, it's recommended to always have a default theme specified.

export default defineNuxtConfig({
  content: {
    highlight: {
      // Theme used in all color schemes.
      theme: 'github-light'
      // OR
      theme: {
        // Default theme (same as single string)
        default: 'github-light',
        // Theme used if `html.dark`
        dark: 'github-dark',
        // Theme used if `html.sepia`
        sepia: 'monokai'
      }
    }
  }
})

highlight.preload

By default, module preloads couple of languages for syntax highlighter: ['diff', 'json', 'js', 'ts', 'css', 'shell', 'html', 'md', 'yaml']{lang=ts}

If you plan to use code samples of other languages, you need to define the language in these options.

export default defineNuxtConfig({
  content: {
    highlight: {
      preload: [
        'c',
        'cpp',
        'java'
      ]
    }
  }
})

If you wish to add highlighting for an unsupported language, you can do so by loading the grammar file for the language.

import { readFileSync } from 'fs'

export default defineNuxtConfig({
  content: {
    highlight: {
      preload: [
        {
          id: 'gdscript',
          scopeName: 'source.gdscript',
          aliases: ['gdscript', 'gd'], // Use to mark code blocks in Markdown
          grammar: JSON.parse(
            readFileSync(
              // Place the language grammar file somewhere in your project
              './shiki/languages/gdscript.tmLanguage.json'
            ).toString()
          ),
        },
      ],
    },
  },
})

Read more about adding languages in the Shiki documentation.

yaml

  • Type: false | Object{lang=ts}
  • Default: {}{lang=ts}

Options for yaml parser.

navigation

  • Type: false or Object{lang=ts}
  • Default: true{lang=ts}

Configure the navigation feature.

Can be set to false to disable the feature completely.

navigation options

Option Type Description
fields string[] A list of fields to inherit from front-matter to navigation nodes.

locales

  • Type: Array<String>{lang=ts}
  • Default: []{lang=ts}

List of locale codes. This codes will be used to detect contents locale.

defaultLocale

  • Type: String{lang=ts}
  • Default: undefined{lang=ts}

Default locale for top level contents. Module will use first locale code from locales array if this option is not defined.

::alert{type="info"} Note that in case of defining multiple locales, Module will filter content with defaultLocale. If you want to fetch contents of another locale, you need to use where option. ::

documentDriven

  • Type: Boolean | Object{lang=ts}
  • Default: false{lang=ts}

Toggles the document-driven mode.

false{lang="ts"} will disable the feature completely.

true{lang="ts"} will enable the feature with these defaults:

{
  // Will fetch navigation, page and surround.
  navigation: true,
  page: true,
  surround: true,
  // Will fetch `content/_theme.yml` and put it in `globals.theme` if present.
  globals: {
    theme: {
      where: {
        _id: 'content:_theme.yml'
      },
      without: ['_']
    }
  },
  // Will use `theme` global to search for a fallback `layout` key.
  layoutFallbacks: ['theme'],
  // Will inject `[...slug].vue` as the root page.
  injectPage: true
}

documentDriven options

Option Type Description
page Boolean Enables the page binding, making it globally accessible.
navigation Boolean Enables the navigation binding, making it globally accessible.
surround Boolean Enables the surround binding, making it globally accessible.
globals Object | Boolean A list of globals to be made available globally.
layoutFallbacks string[] A list of globals key to use to find a layout fallback.
injectPage boolean Inject [...slug].vue pre-configured page
trailingSlash boolean Add a slash at the end of canonical and og:url