Last updated 2 weeks ago

Using custom fonts in Reference docs

You can change the default font in your API documentation to customize its appearance. To prevent the default font settings from overriding your changes, you must import the custom font into your Reference docs HTML template.

Prerequisites

  • Reference docs configuration: Access to Reference docs configuration files
  • Workflows configuration: Redocly Workflows user account with access to the Reference docs Settings > API reference settings page and/or access to Reference docs configuration files

Use custom fonts in Reference docs

  1. Change the font in the configuration file.

In your Reference docs .redocly.yaml configuration file, find or create the theme section under referenceDocs.

To use the same font family for all text in your docs, change the value of the typography.fontFamily key in the theme section.

Example .redocly.yaml file

apiDefinitions:
  default: openapi/example.yaml
referenceDocs:
  showConsole: true
  htmlTemplate: ./web/index.html
  theme:
    sidebar:
      backgroundColor: '#333333'
    typography:
      fontFamily: 'Roboto, sans-serif'

For further customization, you can change the font family used in specific textual elements (like heading levels and inline code). Consult the full Reference docs theming schema for details on which typography-related options are supported.

The following example sets a custom font for inline code, and another custom font for headings.

apiDefinitions:
  default: openapi/example.yaml
referenceDocs:
  showConsole: true
  htmlTemplate: ./web/index.html
  theme:
    sidebar:
      backgroundColor: '#333333'
    typography:
      code:
        fontFamily: 'Ubuntu Mono, monospace'
        fontSize: '10px'
      headings:
        fontFamily: 'Roboto, sans-serif'
        fontWeight: '800'

Save your changes to the .redocly.yaml file.

  1. Import the font into the HTML template.

After specifying one or more custom fonts in the .redocly.yaml file, you must import all those fonts into your Reference docs HTML template.

Import the custom font CSS in the <style> element of the HTML template <head>. Note that you can't import font files (local or remote) - you can only link to web fonts in your HTML template.

Example HTML template

<!DOCTYPE html>
<html>
  <head>
    <title>ACME API Reference Documentation</title>
    <!-- needed for adaptive design -->
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <!--
    ReDoc uses font options from the parent element
    So override default browser styles
    -->
    <style>
      @import url('https://fonts.googleapis.com/css?family=Roboto:400,700');

      body {
        margin: 0;
        padding: 0;
        font-family: Verdana, Geneva, sans-serif;
        font-size: 14px;
        color: #333;
      }
    </style>
    {{{redocHead}}}
  </head>
  <body>
    {{{redocBody}}}
  </body>
</html>

Save your changes to the HTML template file.

  1. Confirm that the custom font is loaded and used.

After building your API documentation, check if the custom font is used in all textual elements for which you configured it.

Configure custom fonts in Workflows

If your Reference docs are hosted in Redocly Workflows, you can use the Live configuration mode to choose from a set of predefined Google Fonts. In this case, it is not required to import the font into the HTML template.

  1. Log into your Workflows organization. In the Reference docs page, select the Reference docs project for which you want to configure a custom font.
  2. On the Reference docs > Settings page, select API reference settings in the sidebar. Then, select the Live configuration button to access the Live configuration mode.
  3. In the Live configuration mode, select Typography in the sidebar on the right to expand the list of configuration options.
  4. To use the same font family for all text in your docs, choose a font in the General > Font family dropdown. To use a custom font for headings, choose a font in the Headings > Headings font family dropdown.
  5. To use a custom font for inline code, select Code in the sidebar, then choose a font in the Font family dropdown. To change the font for field names in request/response schemas, select Other in the sidebar, then choose a font in the Field name font family dropdown.
  6. Select Save changes to confirm your changes. Select Back to settings at the top of the page to exit the Live configuration mode.
  7. Saving your changes triggers a new Reference docs build. When the build is successfully completed and your API documentation published, check the relevant textual elements to confirm that your font changes have been applied.

This procedure applies when you want to use predefined Google Fonts in your reference docs. To use any other custom font, you must use a .redocly.yaml configuration file and modify the Reference docs HTML template. Follow the Step 1 and Step 2 from the on-premise reference docs section for instructions.