diff options
Diffstat (limited to 'blog/2024/01/27/docusaurus-admonition-heading-toc')
| -rw-r--r-- | blog/2024/01/27/docusaurus-admonition-heading-toc/index.mdx | 26 |
1 files changed, 13 insertions, 13 deletions
diff --git a/blog/2024/01/27/docusaurus-admonition-heading-toc/index.mdx b/blog/2024/01/27/docusaurus-admonition-heading-toc/index.mdx index a2d7798b..02e774f4 100644 --- a/blog/2024/01/27/docusaurus-admonition-heading-toc/index.mdx +++ b/blog/2024/01/27/docusaurus-admonition-heading-toc/index.mdx @@ -16,13 +16,13 @@ hide_table_of_contents: false {/* truncate */} -facebookが母体なので色々と気になるところですが、[React](https://ja.legacy.reactjs.org/)を初めとして有益なソフトウェアを完全なオープンソースとして提供してくれていることは純粋にありがたいと感じます。 +Facebookが母体なのでいろいろと気になるところですが、[React](https://ja.legacy.reactjs.org/)を初めとして有益なソフトウェアを完全なオープンソースとして提供してくれていることは純粋にありがたいと感じます。 ## Admonitionのタイトルが見出しにならない -さてDocusaurusには[Admonition](https://docusaurus.io/docs/markdown-features/admonitions)（注意書きや警告文）を容易にmarkdownで書く方法が用意されています。 +さてDocusaurusには[Admonition](https://docusaurus.io/docs/markdown-features/admonitions)（注意書きや警告文）を容易にMarkdownで書く方法が用意されています。 -例えばinfoなら、次のようにmarkdownで書けば、 +たとえばinfoなら、次のようにMarkdownで書けば、 ```mdx title="Admonitionの記法（mdもしくはmdxに記載）" :::info[infoの例] @@ -77,7 +77,7 @@ facebookが母体なので色々と気になるところですが、[React](http ## カスタマイズ後はどうなるか -後述のカスタマイズをすると、Admonitionのタイトル部に（通常の見出しmarkdownと同様に）**#を冒頭に2個以上入れる** ことで見出しになります。またTOCにも反映されます。#を2個以上としているのは、H1をAdmonitionには使わないはずのため。また#を入れない場合は見出しにならず、TOCにも反映されません。 +後述のカスタマイズをすると、Admonitionのタイトル部に（通常の見出しMarkdownと同様に）**#を冒頭に2個以上入れる** ことで見出しになります。またTOCにも反映されます。#を2個以上としているのは、H1をAdmonitionには使わないはずのため。#を入れない場合は見出しにならず、TOCにも反映されません。 ### タイトル冒頭に#を入れた場合 @@ -90,7 +90,7 @@ facebookが母体なので色々と気になるところですが、[React](http ``` ↓ -:::info #### 見出しになりTOCに反映されるタイトルの例 +:::info #### 見出しになり、TOCに反映されるタイトルの例 #が4つ分のためH4見出しになります。TOCにも反映されます。 @@ -109,7 +109,7 @@ facebookが母体なので色々と気になるところですが、[React](http ::: ``` ↓ -:::info #### 見出しにならずTOCに反映されないタイトルの例 +:::info #### 見出しにならず、TOCに反映されないタイトルの例 #がないため見出しになりません。 @@ -141,7 +141,7 @@ facebookが母体なので色々と気になるところですが、[React](http ### RemarkとRehypeについて -RemarkとRehypeは、markdownをHTMLに変換するプロセスにおいて、AST（抽象構文木・Abstract Syntax Tree）に作用するプラグインです。なお[ASTを操作するオープンソースのエコシステム](https://github.com/unifiedjs/unified)の中にはもう一つ[Retext](https://github.com/retextjs/retext)というプラグインもありますが、Docusaurusには実装されていないようです。 +RemarkとRehypeは、MarkdownをHTMLに変換するプロセスにおいて、AST（抽象構文木・Abstract Syntax Tree）に作用するプラグインです。なお[ASTを操作するオープンソースのエコシステム](https://github.com/unifiedjs/unified)の中にはもう１つ[Retext](https://github.com/retextjs/retext)というプラグインもありますが、Docusaurusには実装されていないようです。 ```md title="markdownからHTMLへ変換処理の流れ" | ........................ process ........................... | @@ -159,7 +159,7 @@ Input ->- | Parser | ->- Syntax Tree ->- | Compiler | ->- Output 上図（[Unified Overviewより](https://github.com/unifiedjs/unified?tab=readme-ov-file#overview)）にTransformersとあるところがRemark/Rehypeの動作するところ。 -Remarkはmarkdown形式で、RehypeはHTML形式でASTを扱います。どちらも同じようにASTを操作できますが、データ構造が違うため、目的に応じて選択することになるのかなと思います。 +RemarkはMarkdown形式で、RehypeはHTML形式でASTを扱います。どちらも同じようにASTを操作できますが、データ構造が違うため、目的に応じて選択することになるのかなと思います。 [こちらのサイト](https://vivliostyle.github.io/vivliostyle_doc/ja/vivliostyle-user-group-vol2/spring-raining/index.html)などが詳しいです。 @@ -172,14 +172,14 @@ Docusaurusでこれらのプラグインを利用するためにはdocusaurus.co | Remark<br />Markdown形式 | beforeDefaultRemarkPlugins | remarkPlugins | | Rehype<br />HTML形式 | beforeDefaultRehypePlugins | rehypePlugins | -markdownからHTMLへの変換処理のところで、Docusaurusは自前のプラグイン（デフォルトプラグイン）を使い「見出しにidをつける」「ASTからTOCを作成する」などの処理を行っています。そのため今回のように「Amonitionのタイトルを読んでTOCに反映する」ためには、デフォルトプラグイン適用前と適用後の両方のタイミングでの処理が必要になります。 +MarkdownからHTMLへの変換処理のところで、Docusaurusは自前のプラグイン（デフォルトプラグイン）を使い「見出しにidをつける」「ASTからTOCを作成する」などの処理を行っています。そのため今回のように「Amonitionのタイトルを読んでTOCに反映する」ためには、デフォルトプラグイン適用前と適用後の両方のタイミングでの処理が必要になります。 ### Swizzlingについて -Swizzlingは[こちら](https://docusaurus.io/docs/swizzling)に説明がある通りの機能で、簡単に言うとReactのコンポーネントをカスタマイズできる機能です。 +Swizzlingは[こちら](https://docusaurus.io/docs/swizzling)に説明があるとおりの機能で、簡単に言うとReactのコンポーネントをカスタマイズできる機能です。 -Swizzlingの設定をすると、Docusaurusがデフォルトのコンポーネントの代わりに自動的にカスタマイズしたコンポーネントを使用するようになります。 +Swizzlingの設定をすると、Docusaurusがデフォルトのコンポーネントの代わりに自動的にカスタマイズしたコンポーネントを使用します。 今回は、デフォルトのAdmonitionにないID属性を持たせるためAdmonitionコンポーネントをカスタマイズしました。Swizzlingの設定をすることにより、デフォルトのAdmonitionの代わりにこのカスタムコンポーネントが使われるようにします。 @@ -189,7 +189,7 @@ TOCは「ASTに含まれているheading要素を単純に配列に入れてい 1. docusaurusのデフォルトプラグインがTOCの処理を行うより前に、Admonitionのタイトル部を見出しとして新規作成し、Admonition要素の直前に追加する 1. docusaurusのデフォルトプラグインがTOCの処理を行い、Admonitionのタイトル部がTOCに入る。見出しにはidが付与される -1. デフォルトプラグインの処理が終了したら作成した見出しは不要になるので削除する。その際、削除する見出しと同じタイトルを持つAdmonition要素を探し、idを与える +1. デフォルトプラグインの処理が終了したら作成した見出しは不要になるので削除する。その際、削除する見出しと同じタイトルをもつAdmonition要素を探し、idを与える 1. AdmonitionコンポーネントでidをHTMLタグに付与する @@ -343,7 +343,7 @@ export default plugin; :::note Admonitionのツリー構造 -参考までに、Remarkのプラグインから見るとAdmonitionのASTは例えば次のようになっています。 +参考までに、Remarkのプラグインから見るとAdmonitionのASTはたとえば次のようになっています。 ```javascript title="Admonitionのツリー構造（一例）" { |