Fluorite
1.2.0
Make documentation at ease!
Menu
Version

Template API

The template data is an object available inside a theme's template file (written using Handlebars) which contains all the configuration and the rendered content for each page. Using this data, the theme's index.hbs decides where the content would show up and how the final HTML will look based on the configuration values.

But, before we cover the template API, let's take a look at how Fluorite generates the documentation:

  1. flconfig.json is loaded and all content is read
  2. Both the markdown and the JSON content are rendered into HTML
  3. A template data object is created based on the configuration (content versioning, multipage, etc.)
  4. The docs are generated by running each page's template data (of each version) through the theme's index.hbs

With that in mind, let's look at the data that is available to the index.hbs for rendering the final HTML.

The template data you get in index.hbs is generated specifically for each page, which means the job of index.hbs is to only render the HTML for that specific page. Repeating this for each page of each version (handled by Fluorite) results in the final HTML.

Make sure you're familiar with the output directory and the theme config which helps you to define theme-specific configuration and declare theme assets which affect the final output structure.

The template data of each page has the following properties available to the Handlebars template file:

  • title: The title of the documentation.
  • pageTitle: The current page's title.
  • themeFlavor: The selected theme flavor.
  • multiPage: A boolean indicating if documentation is being generated in multipage mode.
  • version: The version of the current page being rendered.
  • versions: An array of version objects. This array tells the template what versions the whole documentation has.
    • version: The version number.
    • link: A relative link from the current page to this version (either the root document or the same document in that version based on rendererOptions.rootVersionLinksOnly.)
  • path: The section path of the current page. Section paths are index numbers of the sections array with / for sub sections. For example, if the page belongs to Sub 1 section of Section 1 and Section 1 has the index 0, then the section path would be 0/0.
  • sections: An array containing section objects. This array could be used to render the documentation index.
    • title: The section title.
    • link: A relative link to the section from the current page.
    • level: The indentation level of the section.
    • path: The section path.
    • selected: A boolean indicating if the current page belongs to this section.
  • rootPrefix: A path prefix to be inserted at the beginning of all links referring to the documentation root.
  • versionRootPrefix: A path prefix to be inserted at the beginning of all links referring to the root of the current version.
  • contents: An array of section content objects.
    • title: The title of the current section.
    • id: The id of the section title (used for anchors.)
    • content: An array of content objects.
      • type: Either doc or api specifying the content type (markdown or API respectively.)
      • value: The rendered HTML content (string) if type is doc or an object with the following properties if type is api:
        • raw: A copy of the input JSON file (API documentation file). Since most values are already rendered (as tables, code blocks, etc.), the raw property can be used to render any parts differently inside the template. Keep in mind that a body model would be provided with string or JSON content where the externalFile was used (and the externalFile property would be deleted). Also, body property of request and response examples is wrapped as a single-element array.
        • info: Namespace.
          • title: Title of the API (used for headers).
          • id: The id of the API title (used for headers).
          • content: The rendered description.
        • auth: Namespace.
          • enabled: Boolean indicating if authentication is enabled.
          • title: Authentication title (used for headers).
          • id: The id of the authentication title (used for headers).
          • content: The rendered authentication description.
        • path:
          • title: Path title (used for headers).
          • id: The id of the path title (used for headers).
          • method: The path method.
          • content: The path content.
        • params: Namespace.
          • title: Parameters title (used for headers).
          • id: The id of the parameters title (used for headers).
          • content: The parameters content.
        • queries: Namespace.
          • title: The query parameters title (used for headers).
          • id: The id of the query parameters title (used for headers).
          • content: The query parameters content.
        • request: Namespace.
          • headers: Namespace.
            • title: The request headers title (used for headers).
            • id: The id of the request headers title (used for headers).
            • content: The headers rendered content.
          • cookies: Namespace.
            • title: The request cookies title (used for headers).
            • id: The id of the request cookies title (used for headers).
            • content: The cookies rendered content.
          • body: Namespace.
            • title: The request body title (used for headers).
            • id: The id of the request body title (used for headers).
            • content: An array of body objects.
              • type: The body type.
              • value: The rendered body value.
        • response: Same as request.
        • examples: An array of example objects.
          • title: The examples title (used for headers).
          • id: The id of the examples title (used for headers).
          • path: Namespace.
            • title: The path title (used for headers).
            • id: The id of the path title (used for headers).
            • method: The example request method.
            • content: The path content.
          • request: Same as request (documented above).
          • response: Same as request with the following expansions:
            • status: Namespace.
              • title: Status title (used for headers).
              • id: The id of the status title (used for headers).
              • code: The status code.
              • content: The status content (message).
  • extended: A copy of the themeOptions inside flconfig.json. All the declared user assets in the theme's config will have the final calculated value here (refer to User Assets for more info.)

If you need a working example, take a look at the Onyx's index.hbs located at fluorite-root/themes/onyx/index.hbs.

Built-in Helpers

The following built-in Handlebars helpers are available to the templates:

  • isAPI: Takes a value and returns true if it's equal to api (useful for detecting contents.*.content.*.type).
  • isDoc: Same as isAPI but returns true for doc type.
  • isRoot: Takes a value and returns true if it's an empty string (useful for detecting if sections.*.path is root).

Example

The following Handlebars file is a simple example of how the template API may be used:

<html>
  <head>
    {{#if multiPage}}
      <title>{{title}}{{#if path}} - {{pageTitle}}{{/if}}</title>
    {{else}}
      <title>{{title}}</title>
    {{/if}}
  </head>
  <body>
    {{! Render documentation index}}
    <div class="index">
      {{#each sections}}
        <a href="{{link}}">{{version}}</a>
      {{/each}}
    </div>
    {{! Render the current page's content}}
    {{#each contents}}
      <h1 id="{{id}}">{{title}}</h1>
      {{#each content}}
        {{value}}
      {{/each}}
    {{/each}}
  </body>
</html>