docusaurus-theme-plantuml

Theme for displaying PlantUML in docusaurus.

What is this?

en

1. this is a theme for displaying plantuml diagrams on docusaurus.
   1. at first, I tried to make it as a plugin, but it did not work, so I made it as a theme
2. the default setting is to display the results rendered by the plantuml server via https communication.

ja

1. これはdocusaurusにplantumlの図を表示するためのテーマです
   1. 最初、pluginとして作ろうとしましたがうまくいかなかったのでテーマとして作っています
2. デフォルト設定ではhttps通信でplantuml serverにレンダリングさせた結果を表示します

image

1. light mode
   1. 
2. dark mode
   1. 

Precautions before use

en

1. The default rendering destination is the official PlantUML server.
2. Even though it is official, rendering is done via http, so if you handle confidential information, please set up your own server, etc., and use at your own risk.
3. see below
   1. plantuml.com/en/faq - https://plantuml.com/en/faq
      1. How long do the images generated by PlantUML Server live for?

ja

1. デフォルトのレンダリング先はPlantUML公式のサーバーです。
2. 公式とはいえ、httpを介してレンダリングしているので、機密情報を扱う場合には自分でサーバーを立てるなどして、自己責任のうえ活用してください。
3. 以下を参照
   1. plantuml.com/ja/faq - https://plantuml.com/ja/faq
      1. PlantUML Serverで生成した画像はいつまで保持されますか?

How to Use?

install

pnpm add docusaurus-theme-plantuml

or

npm install plugin-docusaurus-plantuml

or

yarn add plugin-docusaurus-plantuml

How to set up on docusaurus

docusaurus.config.js

module.exports = {
  // ...other settings
  themes: [
    require.resolve('docusaurus-theme-plantuml'),
  ]
};

Example of description in markdown

    ## plantuml example

    ```pumld
    @startuml
    Alice -> Bob: Hello
    @enduml
    ```

    or

    ```plantuml-diagram
    @startuml
    start
    :Hello world;
    :This is defined on
    several **lines**;
    stop
    @enduml
    ```

en

1. We also take into account the case where you want to display PlantUML code as markdown and not “plantuml” to render it when
   1. plantuml-diagram
   2. pumld

ja

1. markdownとしてPlantUMLのコードを表示したい場合も考慮して「plantuml」ではなく、以下の場合にレンダリングするようにしています。
   1. plantuml-diagram
   2. pumld

Then build your Docusaurus project

pnpm run build

or

npm run build

or

yarn run build

Options available

| Option | Type | Default | Description | | ---------------- | --------- | ----------------------------------------- | ------------------------- | | serverUrlLight | string | https://www.plantuml.com/plantuml/svg/ | Server URL for light mode | | serverUrlDark | string | https://www.plantuml.com/plantuml/dsvg/ | Server URL for dark mode | | debug | boolean | false | Turn on debug log output |

en

1. by default, the official PlantUML server renders the image in SVG format
2. docker is recommended if you want to prepare your own PlantUML server. specify its server URL as serverUrlLight etc.
   1. reference: dockerhub - https://hub.docker.com/r/plantuml/plantuml-server
3. for example, if you want to render in PNG format, configure as follows

ja

1. デフォルトはPlantUML公式のサーバーでSVG形式にレンダリングしています
2. 自分でPlantUMLサーバーを用意するのであればdockerがオススメです。そのサーバーURLをserverUrlLightなどに指定してください
   1. 参考: dockerhub - https://hub.docker.com/r/plantuml/plantuml-server
3. 例えばPNG形式でレンダリングしたければ以下のように設定します

module.exports = {
  // ...other settings
  themeConfig: [
    plantuml: {
      serverUrlLight: 'https://www.plantuml.com/plantuml/png/',
      serverUrlDark: 'https://www.plantuml.com/plantuml/dpng/',
    },
  ],
};

• Note that the destination is themeConfig, not themes.
• 設定先が themes ではなく、 themeConfig であることに注意してください

Compatibility

en

1. This theme is compatible with Docusaurus v3.9.2 and later versions
2. Tested with Node.js 18.x and later
3. Package manager: pnpm (recommended), npm, or yarn

ja

1. このテーマはDocusaurus v3.9.2以降のバージョンに対応しています
2. Node.js 18.x以降でテスト済み
3. パッケージマネージャー: pnpm(推奨)、npm、またはyarn

Troubleshooting

npm configuration warnings

en

1. If you encounter warnings like "Unknown env config" when running pnpm commands, check your .npmrc files
2. Common deprecated settings that cause warnings:
   1. verify-deps-before-run - This setting is deprecated and should be removed
   2. _jsr-registry - This setting is no longer supported
3. Solution:
   1. Check for .npmrc files in both project root and user home directory (~/.npmrc)
   2. Remove or comment out deprecated settings
   3. Run pnpm run format again to verify warnings are resolved

ja

1. pnpmコマンド実行時に「Unknown env config」のような警告が表示される場合、.npmrcファイルを確認してください
2. 警告の原因となる一般的な非推奨設定:
   1. verify-deps-before-run - この設定は非推奨のため削除してください
   2. _jsr-registry - この設定はサポートされなくなりました
3. 解決方法:
   1. プロジェクトルートとユーザーホームディレクトリ(~/.npmrc)の両方で.npmrcファイルを確認
   2. 非推奨設定を削除またはコメントアウト
   3. pnpm run formatを再実行して警告が解消されたことを確認

Biome configuration issues

en

1. If formatting or linting fails, verify your biome.jsonc configuration file
2. Common issues:
   1. Invalid JSON syntax in configuration file
   2. Missing or incorrect formatter settings
   3. Incompatible rule configurations
3. Solution:
   1. Validate JSON syntax using a JSON validator
   2. Check Biome documentation for correct configuration format
   3. Run pnpm run lint to identify specific configuration problems

ja

1. フォーマットやリントが失敗する場合、biome.jsonc設定ファイルを確認してください
2. よくある問題:
   1. 設定ファイルの無効なJSON構文
   2. フォーマッター設定の欠落または誤り
   3. 互換性のないルール設定
3. 解決方法:
   1. JSONバリデーターを使用して構文を検証
   2. Biomeドキュメントで正しい設定フォーマットを確認
   3. pnpm run lintを実行して具体的な設定問題を特定

Build or test failures

en

1. If build or test commands fail after updating dependencies:
   1. Clear node_modules and reinstall: rm -rf node_modules && pnpm install
   2. Clear build cache: rm -rf lib && pnpm run build
   3. Verify TypeScript configuration is compatible with updated dependencies
   4. Check for breaking changes in dependency changelogs
2. For persistent issues, check the issues page or create a new issue

ja

1. 依存関係更新後にビルドやテストコマンドが失敗する場合:
   1. node_modulesをクリアして再インストール: rm -rf node_modules && pnpm install
   2. ビルドキャッシュをクリア: rm -rf lib && pnpm run build
   3. TypeScript設定が更新された依存関係と互換性があることを確認
   4. 依存関係の変更履歴で破壊的変更を確認
2. 問題が解決しない場合は、issuesページを確認するか、新しいissueを作成してください

Changelog

Checkout the releases page for changelog.