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,
};
},
);
}