Skip to main content

Global Settings

Every WriteDocs documentation site requires a config.json file to handle the essential configuration settings. Explore the available attributes below to get started.

If you prefer to learn by example and then reference the attributes as needed for a deeper understanding, check out this full example.

General​

websiteName string required

The name of your website as it will appear in the website title on search engines. This name is typically the same as your product or company name.

description string required

A brief description of your project or documentation site. This description will be used in metadata for SEO and sharing purposes.

  {
    "websiteName": "MyCompany Docs", // Your website's name
    "description": "Project Description", // a Short description of your site for metadata
    ...
  }

Branding​

images object

Contains paths to various image files used on your site, including the logo and favicon.

  • logo string required
    Path to the primary logo image file, displayed on the documentation site. Usually a PNG or SVG.

  • favicon string required
    Path to the favicon image file in the .ICO format, used in the browser tab. You can quickly convert your .PNG favicon to .ICO using Cloud Convert, for example.

  • darkLogo string
    Path to the logo image file displayed when the site is in dark mode. Ensures visibility against dark backgrounds.

{
  ...
  "images": {
    "logo": "media/logo.png", // Company's logo
    "favicon": "media/favicon.ico", // Site favicon. Needs to be in .ico format
    "darkLogo": "" // (Optional) Company's logo for darkmode
  },
  ...
}
styles object required

Defines the visual appearance of your documentation site, including colors and pagination settings.

  • mainColor string required
    The primary color used for accents and highlights on your documentation site. Usually a hex color code.

  • darkModeMainColor string
    The primary color used for accents and highlights when dark mode is active. This can be left blank if you want to use the same color as the main color.

  • navbarColor string
    The background color of the navigation bar in light mode. If this attribute is not set, WriteDocs will consider the same value of the mainColor.

  • navbarDarkModeColor string
    The background color of the navigation bar in dark mode. Ensures that the navbar is visible against dark backgrounds.

  • pagination boolean
    Enables or disables pagination for the documentation pages. When enabled, users can navigate through sections of the page using pagination controls. Default: false.

{
    ...
  "styles": {
    "mainColor": "#3778fd", // Company's primary color
    "darkModeMainColor": "", // (Optional) Company's darkmode primary color 
    "navbarColor": "#000", // (Optional) Color for the website navigation bar
    "navbarDarkModeColor": "#3778fd", // (Optional) Darkmode color for the website navigation bar
    "pagination": false // (Optional) Define whether to show pagination links at bottom of pages
  },
  ...
}

Color Mode​

colorMode object

Contains configurations to define preferred color scheme.

  • default string
    Defines which is the default color scheme of your documentation. Can either be light or dark. Defaults to light.

  • switchOff boolean
    Define whether to switch on or off the color mode toggle. Defaults as false.

{
    ...
  "colorMode": {
    "default": "dark", // Select the default color schema for your docs
    "switchOff": true, // Switch on/off the toggle to change color mode
  },
  ...
}

API Reference​

apiFiles array of strings

A list of paths to your API definition files, usually in YAML format. These files define the API endpoints, parameters, and responses, and are used to generate API reference documentation.

{
  ...
  "apiFiles": [ // Add the OpenAPI files to generate the API Reference pages
    "example.yml"
  ],
  ...
}

Home Page​

homepage string required

The path to your homepage file. This is the landing page users see when they visit your documentation site.

{
  ...
  "homepage": "/introduction", // Defines a home page for your docs. It can either be a page's slug or the homepage.html file
  // or 
  "homepage": "homepage.html", 
  ...
}
Info

The home page feature is only available starting from the Startup Plan.

Changelog​

changelog boolean

A optional parameter to add a changelog tab to your documentation.

{
  ...
  "changelog": false, 
  ...
}
navbar array of objects required

Defines the structure of the navigation bar. Each object in the array represents a tab or a dropdown menu in the navigation bar.

  • label string required
    The text label displayed in the navbar.

  • sidebarRef string
    A reference to the corresponding sidebar section, linking the navbar item to a specific part of the sidebar. Required if dropdown is not used.

  • dropdown array of objects
    An array of objects used to create a dropdown menu in the navigation bar. Each object in the dropdown array should have a label and sidebarRef to link to specific sections of the sidebar. Required if sidebarRef is not used above.

    • label string required
      The text label displayed in the navbar.

    • sidebarRef string required
      A reference to the corresponding sidebar section, linking the navbar item to a specific part of the sidebar.

{
  ...
  "navbar": [ // Defines the tabs of your navbar
    { // An object with a single label and sidebarRef becomes tab w/o dropdown
      "label": "Guides", // Label that is displayed for this tab on the sidebar
      "sidebarRef": "docs" // Attribute that will be refered in the sidebar configuration
    },
    {
      "label": "API Reference", // An object with a dropdown list becomes a tab with dropdown
      "dropdown": [
        {
          "label": "v1.0", // 
          "sidebarRef": "apiReference" // Attribute that will be refered in the sidebar configuration
        }
      ]
    }
  ],
  ...
}
externalLinks array of objects

WriteDocs allows you to add up to 2 external links in the right side of the navigation bar with this array.

The objects inside this array will be composed of the following attributes:

  • link string required
    The link to redirect the user when they click this button.

  • name string required
    The button name to be shown in the documentation.

sidebars array of objects required

Defines the structure of the sidebar, where users navigate the documentation content. Each object represents a different sidebar.

The objects inside this array will be composed of the following attributes:

  • sidebarRef string required
    The sidebar reference name. This value is used to connect a navbar link to this sidebar item. The WriteDocs template provides "docs" and "apiReference" as the default values for these objects. However, you can change this attribute as needed.

  • categoryName string required
    The name of the category under which pages are grouped.

  • pages array of strings or/and array of objects required
    A list of paths to the markdown files representing the pages under the category. It can can also include groups of nested pages.

    How to define a new page in the sidebar object

    A new page is referenced in the sidebar object by adding the relative path to the respective page

    • page string
      The link to the main page of the group of nested pages.

    • groupName string required
      The label to be displayed on the sidebar for a group nested pages.

    • subpages array of strings or/and array of objects required
      A list of paths to the markdown files for the pages inside the group of nested pages. It can can also include more groups of nested pages.

Ordering

The presentation order of the pages and endpoints on the sidebar will follow the same order defined in the sidebar object.

{
  ...
  "sidebars": [ 
    {
      "sidebarRef": "guides",
      "categories": [
        {
          "categoryName": "Getting Started",
          "pages": [
            "getting-started/overview",
            { 
              "page": "getting-started/quickstart/quickstart",
              "groupName": "Quickstart",
              "subpages": [
                "getting-started/quickstart/beginners-guide"
              ]
            },
            "getting-started/global-settings"
          ]
        }
      ]
    }
  ]
}

Full Example​

{
  "websiteName": "MyCompany Docs", // Your website's name
  "description": "Project Description", // a Short description of your site for metadata
  "images": {
    "logo": "media/logo.png", // Company's logo
    "favicon": "media/favicon.ico", // Site favicon. Needs to be in .ico format
    "darkLogo": "" // (Optional) Company's logo for darkmode
  },
  "styles": {
    "mainColor": "#3778fd", // Company's primary color
    "darkModeMainColor": "", // (Optional) Company's darkmode primary color 
    "navbarColor": "#000", // (Optional) Color for the website navigation bar
    "navbarDarkModeColor": "#3778fd", // (Optional) Darkmode color for the website navigation bar
    "pagination": false // (Optional) Define whether to show pagination links at bottom of pages
  },
  "colorMode": {
    "default": "dark", // Select the default color schema for your docs
    "switchOff": true, // Switch on/off the toggle to change color mode
  },
  "apiFiles": [ // Add the OpenAPI files to generate the API Reference pages
    "example.yml"
  ],
  "homepage": "/introduction", // Defines a home page for your docs. Can either be a page's slug or the homepage.html file
  "changelog": true, // Defines whether to add a changelog to the documentation
  "navbar": [ // Defines the tabs of your navbar
    { // An object with a single label and sidebarRef becomes tab w/o dropdown
      "label": "Guides", // Label that is displayed for this tab on the sidebar
      "sidebarRef": "docs" // Attribute that will be refered in the sidebar configuration
    },
    {
      "label": "API Reference", // An object with a dropdown list becomes a tab with dropdown
      "dropdown": [
        {
          "label": "v1.0", // 
          "sidebarRef": "apiReference" // Attribute that will be refered in the sidebar configuration
        }
      ]
    }
  ],
  "externalLinks": [ // Add up to two links to the right side of the navbar
    {
      "link": "https://github.com/orgs/writedocs/repositories", // the external link to redirect the user
      "name": "Github" // the name to be shown at the navbar
    }
  ],
  "sidebars": [ // Define the different sidebars your docs can have (e.g, Guides and API Reference)
    {
      "sidebarRef": "guides", // The name of the sidebar. Referred in the navbar definition as sidebarRef.
      "categories": [
        {
          "categoryName": "Getting Started", // The name of the category of the current sidebar
          "pages": [ // The pages in this category
            "getting-started/overview", // The slugs for the pages in this category
            { // An object will add a group of nested pages inside the category
              "page": "getting-started/quickstart/quickstart", // (Optional) Adds a page as the main link of this group of nested pages
              "groupName": "Quickstart", // Defines the name of the group of nested pages
              "subpages": [ // Adds pages to the group of nested pages
                "getting-started/quickstart/beginners-guide"
              ]
            },
            "getting-started/global-settings"
          ]
        },
        {
          "categoryName": "Creating Pages",
          "pages": [
            "creating-pages/mdx-pages",
            "creating-pages/api-pages",
            "creating-pages/markdown-basics",
            {
              "page": "creating-pages/components",
              "groupName": "Components",
              "subpages": [
                "creating-pages/components/accordions",
                "creating-pages/components/callouts",
                "creating-pages/components/cards",
                "creating-pages/components/codeblocks",
                "creating-pages/components/media"
              ]
            }
          ]
        }
      ]
    },
    {
      "sidebarRef": "apiReference",
      "categories": [
        {
          "categoryName": "Example",
          "pages": [
            "reference/example/get-items",
            "reference/example/create-item"
          ]
        }
      ]
    }
  ]
}