typedoc-plugin-frontmatter

typedoc-plugin-frontmatter

A plugin for TypeDoc that prepends configurable frontmatter to page content.

What does it do?

Exposes a set of options to generate frontmatter on TypeDoc generated pages.

The primary motivation of this plugin is to enable configurable frontmatter on pages generated by typedoc-plugin-markdown, but can also be used with HTML themes if applicable.

Frontmatter can be configured through options and writing a local plugin.

Installation

npm install typedoc-plugin-frontmatter --save-dev

Usage

Please visit TypeDoc for general configuation usage, but typically configuration is set with a typedoc.json file.

typedoc --plugin typedoc-plugin-frontmatter

Options

The following options are exposed by the plugin:

• --frontmatterGlobals (object)
  Specify global static variables as JSON to be added to all frontmatter blocks.
• --frontmatterTags (array)
  Specify the names of the comment @ block tags that should be added to frontmatter variables.
• --frontmatterTagsToSnakeCase (boolean)
  Converts the variable names of comment tags to snake case.

Setting global variables

Global variables can be added to all frontmatter blocks by passing a JSON object to the --frontmatterGlobals option.

typedoc.json

{
  "frontmatterGlobals": {
    "layout": "docs",
    "sidebar": true
  }
}

Frontmatter

---
layout: docs
sidebar: true
---

Using comment tags

Frontmatter variables can be added by extracting comments from block tags defined with the --frontmatterTags option.

Please note tags must be added to the comment blocks of the symbol exported to a page.

For example, the following will mark "author" and "description" tags as frontmatter.

typedoc.json

{
  "frontmatterTags": ["author", "description"]
}

Comment block

/**
 * @module SomeModule
 *
 * @author Joe Bloggs
 *
 * @description A description that will be added to 'frontmatter'.
 *
 **/

Frontmatter

---
author: Joe Bloggs
description: "A description that will be added to 'frontmatter'."
---

Snake case variable names

Tag that are written using snake case tag format will be ignored by the compiler. If snake case format for variable names are required then the option --frontmatterTagsToSnakeCase should be set.

{
  "frontmatterTagsToSnakeCase": true
}

Comment block

/**
 * @moreData Something
 *
 **/

Frontmatter

---
more_data: 'Something'
---

Configuring using a local plugin

For advanced use a local plugin can be written to listen for the emitted frontmatter event (FrontmatterEvent.PREPARE_FRONTMATTER) and then update the frontmatter config before it is written the page.

The event returns:

• event.frontmatter - The current frontmatter JSON object that will be paresed and written to the page. This can be updated with the spread operator additional items.
• event.page - The current page that is being written.

typedoc.json

{
  "plugin": ["typedoc-plugin-frontmatter", "./dist/custom-plugin.js"]
}

custom-plugin.ts

import { Application } from 'typedoc';
import { FrontmatterEvent } from 'typedoc-plugin-frontmatter';

// All plugins should export a `load()` function
export function load(app: Application) {
  // Listen to PREPARE_FRONTMATTER event
  app.renderer.on(
    FrontmatterEvent.PREPARE_FRONTMATTER,
    (event: FrontmatterEvent) => {
      // Update event.frontmatter object using information from the page model as JSON
      event.frontmatter = {
        // e.g add a title
        title: event.page.model?.name,
        // e.g add nav order for classes
        ...(page.model?.kindOf(ReflectionKind.Classs) && { nav_order: 1 }),
        // spread the existing frontmatter
        ...event.frontmatter,
      };
    },
  );
}

License

MIT