Skip to content

Latest commit

 

History

History
494 lines (347 loc) · 13.6 KB

configuration.mdx

File metadata and controls

494 lines (347 loc) · 13.6 KB
title description
Configuration
Configure your documentation with a docs.json file.

Add a docs.json file to the root of your GitHub repository to configure your documentation. Below is a list of all available configuration options, which can be used to modify the logos, theme, analytics and more.

If your IDE supports JSON Schemas, you can add a $schema property to your docs.json file to enable autocompletion and validation:

{
  "$schema": "https://docs.page/schema.json"
}

Properties

Top-level properties

The name of your project. This will be displayed in the header of your documentation and used for other aspects such as automatic social preview images.
A short description of your project. This will be used in meta tags and social preview images.
Defines the favicon to show in the browser tab.

See Asset URLs for more information on how to add assets to your documentation.

The favicon can either be a string value which will be used for both light and dark modes, or a Favicon object to define separate favicons for light and dark modes.

The Asset URL of your favicon to display when the documentation is in light mode. 
---

<Property name="dark" type="string">
  The Asset URL of your favicon to display when the documentation is in dark mode.
</Property>
An asset URL to use as the default social preview image for your documentation.

If not provided, a social preview image will be automatically generated. Individual pages can override this social preview URL by specifying a socialPreview property in their frontmatter.

See Asset URLs for more information on how to add assets to your documentation.

Logo

Configures the logo of your documentation, which will be displayed in the header and used for social preview images.

The minimum height of the logo should be 24px. Note that if only a light or dark logo is provided, it will be used for both light and dark modes.

See Asset URLs for more information on how to add assets to your documentation.

The Asset URL of your logo to display when the documentation is in light mode. 
---

<Property name="dark" type="string">
  The Asset URL of your logo to display when the documentation is in dark mode.
</Property>

Theme

Configures the theme of your documentation. If not provided, a default theme will be used. The default theme of your documentation. This will be used when the user has not manually selected a theme. 
---

<Property name="primary" type="string">
  A hex color code to use as the primary color of your documentation. This color will be used for links, buttons, and other interactive elements.
</Property>

---

<Property name="primaryLight" type="string">
  A hex color code to use as the primary color of your documentation in light mode. If not specified, the `primary` color will be used.
</Property>

---

<Property name="primaryDark" type="string">
  A hex color code to use as the primary color of your documentation in dark mode. If not specified, the `primary` color will be used.
</Property>

---

<Property name="backgroundLight" type="string">
  A hex color code to use as the background color of your documentation in light mode.
</Property>

---

<Property name="backgroundDark" type="string">
  A hex color code to use as the background color of your documentation in dark mode.
</Property>

Header

Configures the header of your documentation. Whether to show the documentation `name` next to the logo in the header. Defaults to `true`. 
---

<Property name="showThemeToggle" type="boolean">
  Whether to show the theme toggle button in the header. Defaults to `true`.
</Property>

---

<Property name="showGitHubCard" type="boolean">
  Whether to show the GitHub card in the header. Defaults to `true`.
</Property>

---

<Property name="links" type="Link[]">
  An array of `Link` objects to display in the header of your documentation.

  <Accordion title="Link">
    <Property name="href" type="string" required>
      The URL to link to.
    </Property>

    ---

    <Property name="title" type="string" required>
      The text to display for the link.
    </Property>

    ---

    <Property name="cta" type="boolean">
      Whether to display the link as a call-to-action button. Defaults to `false`.
    </Property>

    ---

    <Property name="locale" type="string">
      If provided, only show this link when viewing the documentation for a specific [locale](/locales).
    </Property>
  </Accordion>
</Property>

Anchors

Configures the anchor links of your documentation. The title of the anchor link. 
---

<Property name="href" type="string" required>
  The URL to link to.
</Property>

---

<Property name="icon" type="string" required>
  The [icon](/components/icons) to display next to the anchor link.
</Property>

---

<Property name="locale" type="string">
  If provided, only show this anchor when viewing the documentation for a specific [locale](/locales).
</Property>

---

<Property name="tab" type="string">
  If provided, only show this anchor when viewing a specific [tab](/navigation#tabs).
</Property>

Social Links

An object of key value pairs where the key is the social platform and the value is the username/ID to link to: 
{
  "social": {
    "x": "@invertaseio",
    "github": "invertase"
  }
}
A generic website URL to link to, such as your homepage or product. 
---

<Property name="x" type="string">
  The name of your X/Twitter account, e.g. `@invertaseio`.
</Property>

---

<Property name="youtube" type="string">
  The name of your YouTube account.
</Property>

---

<Property name="facebook" type="string">
  The name of your Facebook account.
</Property>

---

<Property name="instagram" type="string">
  The name of your Instagram account.
</Property>

---

<Property name="linkedin" type="string">
  The name of your LinkedIn account.
</Property>

---

<Property name="github" type="string">
  The name of your GitHub account.
</Property>

---

<Property name="slack" type="string">
  The subdomain of your Slack organization.
</Property>

---

<Property name="discord" type="string">
  The name of your Discord organization.
</Property>

SEO

Configures the SEO settings of your documentation. Whether to instruct search engines not to index your documentation. Defaults to `false`.

Variables

An object of common variables which can be replaced in your documentation content using the `{{ variableName }}` syntax. For example, the following: 
{
  "variables": {
    "versions": {
      "default": "1.0.0",
    }
  }
}

Can be replaced via the {{ versions.default }} syntax in your documentation content.

Search

Configures the search settings of your documentation. Whether to enable search via Algolia DocSearch in your documentation. See [Search](/search) for more information on how to configure DocSearch. 
  <Accordion title="DocSearch">
    <Property name="appId" type="string" required>
      The DocSearch application ID for your documentation.
    </Property>

    ---

    <Property name="apiKey" type="string" required>
      The DocSearch API key for your documentation.
    </Property>

    ---

    <Property name="indexName" type="string" required>
      The DocSearch index name for your documentation.
    </Property>
  </Accordion>
</Property>

Scripts

Configures the scripts to include in your documentation. The Google Tag Manager ID to include in your documentation. 
---

<Property name="googleAnalytics" type="string">
  The Google Analytics ID to include in your documentation.
</Property>

---

<Property name="plausible" type="string | boolean">
  If provided and your documentation uses a [Custom Domain](/custom-domains), the [Plausible Analytics](https://plausible.io/) domain to include in your documentation.

  If set to `true`, the default Plausible Analytics script (`https://plausible.io/js/plausible.js`) will be used. Provide a string to use a custom self hosted Plausible Analytics script.
</Property>

Content

Configures how the content of your documentation is displayed. The maximum heading depth to display in the table of contents. Defaults to `3`. 
---

<Property name="zoomImages" type="boolean">
  Whether to enable image zooming by default for all images in your documentation. Defaults to `false`.

  See the [`<Image />`](/components/images) component for more information on how to enable image zooming for specific images.
</Property>

---

<Property name="automaticallyInferNextPrevious" type="boolean">
  Whether to automatically infer the next and previous page links based on your sidebar navigation. Defaults to `true`.
</Property>

---

<Property name="showPageTitle" type="boolean">
  Whether to automatically show the page title from frontmatter at the top of each page. Defaults to `true`.
</Property>

---

<Property name="showPageImage" type="boolean">
  Whether to automatically show the page social image from frontmatter at the top of each page. Defaults to `true`.
</Property>

Tabs

An array of `Tab` objects to display at the top of your documentation. See [Navigation](/navigation#tabs) for more information on how to configure tabs. The unique ID of the tab. 
---

<Property name="title" type="string" required>
  The title of the tab to display.
</Property>

---

<Property name="href" type="string" required>
  The URL to link to when the tab is clicked.
</Property>

---

<Property name="locale" type="string">
  If provided, only show this tab when viewing the documentation for a specific [locale](/locales).
</Property>

Sidebar

An array or object of `Sidebar` objects to display in the sidebar of your documentation. See [Navigation](/navigation#sidebar) for more information on how to configure the sidebar. The page links to display in the sidebar. 
  <Accordion title="Page" defaultOpen>
    <Property name="title" type="string" required>
      The title of the sidebar item.
    </Property>

    ---

    <Property name="href" type="string" required>
      The URL to link to when the sidebar item is clicked.
    </Property>

    ---

    <Property name="icon" type="string">
      The [icon](/components/icons) to display next to the sidebar item.
    </Property>
  </Accordion>
</Property>

---

<Property name="group" type="string">
  The group title to display the sidebar item in. If not provided, the sidebar item will be displayed at the top level.
</Property>

---

<Property name="href" type="string">
  The URL to link to when the sidebar item is clicked.
</Property>

---

<Property name="icon" type="string">
  The [icon](/components/icons) to display next to the sidebar item.
</Property>

---

<Property name="tab" type="string">
  If provided, only show this sidebar item when viewing a specific [tab](/navigation#tabs).
</Property>