HomeDocumentationThemesBlog

General

IntroductionGetting startedWriting MDXBuilt-in componentsDocument settingsDeploying your docsUsage in monorepoUsage with CSS PreprocessorsUsage with TypeScript

Customizing

Powered by GatsbyGatsby ThemeCreating your themesAdd Favicon and MetadataComponent ShadowingCustomizing Webpack Config

References

Migration GuideProject Configuration
Env fileCLI argumentsBasic configThemingBuild pipeline
Components & Hooks APICreating PluginsMDX Plugins

Project Configuration

The project configuration is used when you need to define some specific customizations on your project. Like use plugins, chose themes, set project title, and other things.

To customize your project configuration you can use doczrc.js following this reference.

Env file

You can also create a .env file or use an existing .env file. You can then define customizations via DOCZ_<config-variable>.

CLI arguments

You can also pass customizations as arguments to the docz dev command: docz dev --typescript --port=4838

Basic config

base

  • Type: string
  • Default: process.env.DOCZ_BASE || '/'

The base URL of the site will be deployed at. You will need to set this if you plan to deploy your site under a subpath, for example, GitHub pages. If you plan to deploy your site to https://foo.github.io/bar/, the base should be set to /bar/.

It should always start and end with a slash.

The base is automatically prepended to all URLs that start with / in other options, so you only need to specify it once.

src

  • Type: string
  • Default: process.env.DOCZ_SOURCE || './'

Define the source folder of your components. Only the files in this folder will be parsed. Every file out of this folder will not be found.

Tips and tricks

If you want to boost performance, you can limit the amount of files parsed by passing your source folder here!

files

  • Type: string or Array<string>
  • Default: process.env.DOCZ_FILES || '**/*.{md,markdown,mdx}'

Glob pattern used to find your files. By default, Docz finds all files inside the source folder that have a .mdx extension.

As of v0.10, you can customize it to resolve other filetypes:

// doczrc.js
export default {
  files: '**/*.{md,markdown,mdx}'
  // or files: ['**/*.{md,markdown,mdx}']
}

You can be more specific if you want and change this glob to find other rules.

It is important to keep the .mdx extension in this string if you specify it

ignore

  • Type: string[]
  • Default: ['readme.md', 'changelog.md', 'code_of_conduct.md', 'contributing.md', 'license.md'],

Option used to ignore files to be parsed by docz.

dest

  • Type: string
  • Default: process.env.DOCZ_DEST || '.docz/dist'

Specify the output directory for docz build

title

  • Type: string
  • Default: process.env.DOCZ_TITLE || name as defined in package.json

The title for your site. This will be the prefix for all page titles and displayed in the sidebar in the default theme.

description

  • Type: string
  • Default: process.env.DOCZ_DESCRIPTION || description as defined in package.json

The description for the site. It will be rendered as a <meta> tag in the page HTML.

typescript

  • Type: boolean
  • Default: process.env.DOCZ_TYPESCRIPT || false

This option is used if you need to import Typescript components inside your .mdx files.

propsParser

  • Type: boolean
  • Default: process.env.DOCZ_PROPS_PARSER || true

To be able to use the <Props /> component and parse properties of your components, we need to run a lot of processes that have some costs on the build process. If you need to disable this process to improve performance, you can set this property to false.

config

  • Type: String
  • Default: 'docz.json | .doczrc | doczrc.json |doczrc.js | docz.config.js | docz.config.json'

Use this option to change the filepath of Docz config file.

public

  • Type: string
  • Default: /public

Option used to set a public folder of your project

export default {
  public: '/public'
}

Then you can get assets from your folder:

// my-file.mdx
# Hello

![placeholder image](/public/some-image.png)

debug

  • Type: boolean
  • Default: process.env.DEBUG || false

Use this setting to debug your application and remove all progress bar from bundler.

editBranch

  • Type: string
  • Default: master

Branch used to edit your document when clicking on Github button.

host

  • Type: string
  • Default: process.env.DOCZ_HOST || '127.0.0.1'

Specify the host to use for the dev server.

port

  • Type: number
  • Alias: p
  • Default: process.env.DOCZ_PORT || 3000

Specify the port to use for the dev server.

Theming

theme

This property was removed in the v2

Get more information about how to use it here

wrapper

This property was removed in the v2.

Get more information about how to use it here

themeConfig

  • Type: Object
  • Default: {}

This is the config that you can use to customize your theme. By default, each theme has its own themeConfig that you can modify, so this object may vary according to each theme.

You can see the theme config of default theme here

Build pipeline

  • Type: Array[]
  • Default: null

Use this option to specify the order of your documents in the menu. You can pass a simple string or if you want to order a nested menu you can pass an object with the name of your document and the menu order of it.

export default {
  menu: [
    'Getting Started',
    { name: 'Components', menu: ['Alert', 'Button'] }
  ]
}

plugins

  • Type: Array
  • Default: []

Specify an array of plugins that you want to use.

mdPlugins

  • Type: Array
  • Default: []

Array of remark plugins to manipulate the MDXAST

hastPlugins

  • Type: Array
  • Default: []

Array of rehype plugins to manipulate the MDXHAST

onCreateWebpackChain

This property was removed in v2. Use Gatsby hooks instead.

More info about it here

modifyBundlerConfig

This property was removed in v2. Use Gatsby hooks instead.

More info about it here

modifyBabelRc

This property was removed in v2. Use Gatsby hooks instead.

More info about it here