From bd0cab1f2d198681dd9eb6b2ccf2beeca43ce5e3 Mon Sep 17 00:00:00 2001 From: 安竹洋平 <61961825+yasutakeyohei@users.noreply.github.com> Date: Mon, 29 Jan 2024 09:30:32 +0900 Subject: build --- build/blog/rss.xml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'build/blog/rss.xml') diff --git a/build/blog/rss.xml b/build/blog/rss.xml index 94aea561..d128f782 100644 --- a/build/blog/rss.xml +++ b/build/blog/rss.xml @@ -14,10 +14,10 @@ https://yasutakeyohei.com/docs/blog/2024/01/27/docusaurus-admonition-heading-toc Sat, 27 Jan 2024 00:00:00 GMT - Docusaurusはスゴイね🦖​ -

1ヵ月弱使いましたが、このDocusaurus（ドキュサウルス）は数あるCMSの中でも秀逸です。

+ Docusaurus🦖​ +

1ヵ月弱使いましたがこのDocusaurus（ドキュサウルス）は数あるCMSの中でも秀逸です。

文書作成と管理が容易で、拡張の自由度も非常に高く、完全なオープンソース。

-

議員活動に重要な「資料を作成しまとめて公開するツール」として現状の最適解ではないでしょうか。

+

議員活動に重要な「資料を作成しまとめて公開するツール」として現状の最適解と感じます。

facebookが母体なので色々と気になるところですが、Reactを初めとして有益なソフトウェアを完全なオープンソースとして提供してくれていることは純粋にありがたいと感じます。

Admonitionのタイトルが見出しにならない​

@@ -28,14 +28,14 @@
infoの例

ここに文章を書く

しかし（DocusaurusV3.1）でこのAdmonitionのタイトルは見出し（Heading）にならず、目次（TOC）にも乗りません。上記例なら「INFOの例」がTOCに表示されません。

次の図からも分かっていただけるかと思います。

-

Admonitionのタイトルが見出しにならない

+

Admonitionのタイトルが見出しになら�ない

些細なことのようにも思えますが、Docusaurusを書籍のように扱うには結構気になるところ。

なお以前はAdmonitionのタイトルはH5要素になっていたようですが、深さ（H1～H5のレベル）を決め打ちするのは好ましくないということから（？）、今はH5要素ではありません。

次のように本文中に見出しを書く方法もありますが

Admonitionの記法（mdもしくはmdxに記載）
:::info

#### テスト

～文章～

:::

見た目がイマイチになります。

備考

テスト​

～文章～

-

ほかのユーザーからの要望も上がっており、私も少し不便に感じていたので、次の仕様になるようカスタマイズしました。そのカスタマイズ方を紹介する記事です。

+

ほかのユーザーからの要望も上がっており、私も少し不便に感じていたので、次の仕様になるようカスタマイズしましたのでその方法を解説します。

カスタマイズ後はどうなるか​

後述のカスタマイズをすると、Admonitionのタイトル部に（通常の見出しmarkdownと同様に）#を冒頭に2個以上入れる ことで見出しになります。またTOCにも反映されます。#を2個以上としているのは、H1をAdmonitionには使わないはずのため。また#を入れない場合は見出しにならず、TOCにも反映されません。

タイトル冒頭に#を入れた場合​

@@ -73,7 +73,7 @@

Swizzlingはこちらに説明がある通りの機能で、簡単に言うとReactのコンポーネントをカスタマイズできる機能です。

Swizzlingの設定をすると、Docusaurusがデフォルトのコンポーネントの代わりに自動的にカスタマイズしたコンポーネントを使用するようになります。

今回は、デフォルトのAdmonitionにないID属性を持たせるためAdmonitionコンポーネントをカスタマイズしました。Swizzlingの設定をすることにより、デフォルトのAdmonitionの代わりにこのカスタムコンポーネントが使われるようにします。

-

動作原理​

+

動作原理​

TOCは「ASTに含まれているheading要素を単純に配列に入れている」だけですが、この処理はカスタマイズで上書きできません。そこで、カスタマイズできる処理だけでAdmonitionのタイトルをTOCに反映する方法として次を思いつき、実装しました。

  1. docusaurusのデフォルトプラグインがTOCの処理を行うより前に、Admonitionのタイトル部を見出しとして新規作成し、Admonition要素の直前に追加する
    2. @@ -86,7 +86,7 @@

    まずdocusaurus.config.jsonにimportとplugin設定を記入します（ハイライト部）。

    これでDocusaurusデフォルトプラグイン適用の前後にそれぞれ自作のRemark/Rehypeプラグインが実行されることになります。

    blogなどを入れている場合は、そのプロパティにも記載します。

    -
    docusaurus.config.json
    import admonitionTitleToHeadingBeforeTOC from './src/remark/admonition-title-to-heading-before-toc.js';
    import admonitionTitleToHeadingAfterTOC from './src/rehype/admonition-title-to-heading-after-toc.js';

    export default {
        // ...
        presets: [
        [
            'classic',
            /** @type {import('@docusaurus/preset-classic').Options} */
            ({
            docs: {
                // ...
                beforeDefaultRemarkPlugins: [admonitionTitleToHeadingBeforeTOC],
                rehypePlugins: [admonitionTitleToHeadingAfterTOC],
            },
            blog: {
                // ...
                beforeDefaultRemarkPlugins: [admonitionTitleToHeadingBeforeTOC],
                rehypePlugins: [admonitionTitleToHeadingAfterTOC],
            },
            // ...
            }),
        ]],
        // ...
    }
    +
    docusaurus.config.json
    import admonitionTitleToHeadingBeforeTOC from './src/remark/admonition-title-to-heading-before-toc.js';
    import admonitionTitleToHeadingAfterTOC from './src/rehype/admonition-title-to-heading-after-toc.js';

    export default {
        // ...
        presets: [
        [
            'classic',
            /** @type {import('@docusaurus/preset-classic').Options} */
            ({
            docs: {
                // ...
                beforeDefaultRemarkPlugins: [admonitionTitleToHeadingBeforeTOC],
                rehypePlugins: [admonitionTitleToHeadingAfterTOC],
            },
            blog: {
                // ...
                beforeDefaultRemarkPlugins: [admonitionTitleToHeadingBeforeTOC],
                rehypePlugins: [admonitionTitleToHeadingAfterTOC],
            },
            // ...
            }),
        ]],
        // ...
    }

    Remark/Rehypeプラグイン​

    次にプラグインを実装します。

    docusaurusのsrcディレクトリ下にrehypeとremarkというディレクトリを作り、次のファイル名と内容で2つのプラグインを作ります。

    -- cgit v1.2.3-54-g00ecf