Basedoc projects use a basedoc.json file to configure settings, such as the project's title, navigation, theming and more.

Most of the settings apply to your hosted documentation site.

Get started

Add a basedoc.json file to your project's root directory.

{
  "$schema": "https://basedoc.co/basedoc.schema.json",
  "title": "My Project",
  "description": "This is a description of my project.",
  "navigation": [
    "index",
    "quickstart"
  ]
}

The config file's schema can be added from https://basedoc.co/basedoc.schema.json.

In your code editor, you should be able to see autocomplete, validation and inline hints for your config file. For example, in VS Code or Cursor, you can enable JSON Schema validation by adding the following to your settings.json file:

{
  "json.schemaDownload.enable": true,
}

Basic configuration options

Below are the basic configuration options available for your project.

title

The title of the project. This is used as the title of the project's website.

{
  "title": "My Project"
}

description

The description of the project. This is used as the description of the project's website and will show up in search engine results.

{
  "description": "This is a description of my project."
}

layout

The layout of your hosted site. Currently only one layout is supported: default.

{
  "layout": "default"
}

favicon

The favicon of the project. This is used to configure the project's favicon.

The value should be the relative path to the favicon from the root of your project.

{
  "favicon": "/media/favicon.ico"
}

highlightColors

Use your brand colour for links, buttons and icons.

If not provided, a standard blue colour will be used.

If you provide only one colour, it will be used for both modes.

darkMode gives the option to use a more muted brand colour when your site is in dark mode.

When using brand colours, button text will be white in both dark and light modes.

{
  "highlightColors": {
    "lightMode": "#ff7a00",
    "darkMode": "#d96800"
  }
}

logo

The logo of your hosted site, shown in the top left of your hosted site.

Your logos should be stored in the /media directory.

The lightMode logo is used by default. If you want a different logo in dark mode, you can specify it using the darkMode property.

{
  "logo": {
    "lightMode": "/media/logo.png",
    "darkMode": "/media/logo-darkmode.png"
  }
}

homepage

Your site's homepage is /index.mdx by default.

If you want a different page to load at your site's root, use the homepage config property.

Input a page's path or use a page object with path and title properties.

"homepage": "intro"

"homepage": {"path": "intro", "title": "Welcome to our docs"}

externalLinks

Add links to your header. Great for linking to related places like your app or marketing website.

The value should be a list of external link objects, containing:

• title - The text displayed in the link
• href - The URL of the link
• isExternal (optional) - boolean, used to indicate if the link should open in a new tab
• highlight (optional) - boolean, used to highlight certain links in your brand/highlight colour

"externalLinks": [
  {"title": "Log in", "href": "https://basedoc.co/projects", "isExternal": true}
]

postCollections

Add post collections to your project.

"postCollections": [
  {"directory": "changelog", "title": "Changelog"}
]

• directory: the folder containing your post files (e.g., "blog", "changelog"). The folder name will become the URL path of your post collection.
• indexLayout: (optional) the layout of the index page. Can be "list", "list-full" or "list-compact". Default: "list"
• pageSize: (optional) the number of posts to show per page. Default: 15
• title: (optional) the title of the post collection. Defaults to capitalised directory name.
• description: (optional) the description of the post collection. Shown on index page and in meta tags

Other configuration options