@tats-u/docusaurus-plugin-copy-temml-assets

docusaurus-plugin-copy-temml-assets plugin

This plugin copies Temml assets to the build directory.

Demo: https://tats-u.github.io/docusaurus-plugin-copy-temml-assets (uses Noto Sans Math)

Why Temml instead of KaTeX?

• Can use the other fonts (including local fonts) than Latin Modern.
• Can reduce the download size if you stick to local fonts.
• Can reduce the number of deployment files.
• Supports more LaTeX features.
• Output is simpler (KaTeX outputs invisible MathML tags too).

How to Use

Install the plugin and @daiji256/rehype-mathml (instead of rehype-katex):

npm install @tats-u/docusaurus-plugin-copy-temml-assets @daiji256/rehype-mathml

This package exports the following plugin and companion types and variables:

Name	Description
copyTemmlAssetsPlugin	Docusaurus plugin to copy KaTeX assets
CopyTemmlAssetsPluginOptions	Configuration options for the plugin
getTemmlStyleSheet	Ditto, but with custom base URL
getTemmlCssPath	Ditto, but with custom base URL

Then add plugins to docusaurus.config.js:

import remarkMath from 'remark-math';
import rehypeMathml from '@daiji256/rehype-mathml';
import { copyTemmlAssetsPlugin, getTemmlStyleSheet } from '@tats-u/docusaurus-plugin-copy-temml-assets';

/**
 * @import { CopyTemmlAssetsPluginOptions } from '@tats-u/docusaurus-plugin-copy-temml-assets';
 */

const remarkPlugins = [remarkMath];
// Use @daiji256/rehype-mathml instead of rehype-katex
const rehypePlugins = [rehypeMathMl];

const baseUrl = '/';

// You must use satisfies in TypeScript
const temmlPluginOptions = /** @satisfies {CopyTemmlAssetsPluginOptions} */ ({
  baseUrl,
  fontPath: 'path/to/font.woff2',
});

const config = {
  // ...
  baseUrl,
  stylesheets: [
    // ...
    getTemmlStyleSheet(temmlPluginOptions),
  ],
  plugins: [
    // ...
    [copyTemmlAssetsPlugin, temmlPluginOptions],
  ],
  // ...
  presets: [
    [
      'classic',
      /** @satisfies {import('docusaurus/preset-classic').PresetConfig} */ (
        {
          docs: {
            // If you use docs
            docs: {
              // ...
              remarkPlugins,
              rehypePlugins,
            },
            // If you use blog
            blog: {
              // ...
              remarkPlugins,
              rehypePlugins,
            },
            // If you customize pages
            pages: {
              // ...
              remarkPlugins,
              rehypePlugins,
            },
          },
        },
      ),
    ],
  ],
}

[!NOTE] For TypeScript, use the following instead:

import {
  type CopyTemmlAssetsPluginOptions,
  copyTemmlAssetsPlugin,
  getTemmlStyleSheet,
} from '@tats-u/docusaurus-plugin-copy-temml-assets';

Compatibility with Docusaurus Faster

This plugin is compatible with Docusaurus Faster.

Configuration

The default deployed path is /assets/temml-{Temml version}/Temml-{Font type}.css. If you want to change the path, pass assetsRoot to the plugin:

const temmlPluginOptions = /** @satisfies {CopyTemmlAssetsPluginOptions} */ ({
  baseUrl,
  fontPath: 'path/to/font.woff2',
  assetsRoot: 'assets/temml',
});

[!NOTE] For TypeScript, use { ... } satisfies CopyTemmlAssetsPluginOptions instead.

fontPreset is automatically detected from the basename of fontPath if not specified. If the basename is irregular, you can specify it manually:

const temmlPluginOptions = /** @satisfies {CopyTemmlAssetsPluginOptions} */ ({
  baseUrl,
  fontPath: 'path/to/stix2.woff2', // Standard name: STIXTwoMath.woff2
  fontPreset: 'STIX2',
});

Acknowledgement

This plugin is derived from docusaurus-copy-plugin. Thanks to Ramón Lamana (@rlamana) for the original work.