@tats-u/docusaurus-plugin-copy-temml-assets v1.0.0

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:

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.