🌟

GitHub上のコードを見せながら説明するドキュメントの作り方

1 min read

Facebook...じゃなかった、Meta製のドキュメントツール「Docusaurus」には、「GitHubのコードを埋め込む」プラグインがある。それを使えば、実際のコードを使った説明ができる。

Docusaurusのセットアップ

https://docusaurus.io

セットアップ手順は割愛する。

埋め込みプラグインを入れる

https://github.com/saucelabs/docusaurus-theme-github-codeblock
yarn add @saucelabs/theme-github-codeblock
docusaurus.config.js
+    themes: [
+        '@saucelabs/theme-github-codeblock'
+    ],

docusaurus.config.jsにプラグインをテーマとして追加する。(どっちだよ)

GitHubのURLを取得する

コミットハッシュを含むURL

Copy GitHub PermalinkでGitHubのURLをコピーできる。

ドキュメント自体を製品に合わせてバージョニングしている場合は、こちらが適切。

ただ、Docusaurusのバージョニングはかなり手間がかかるので、大抵は後者のURLを使うことが多いだろう。

コミットハッシュを含まないRL

Open File on Remoteでブラウザを開き、URLをコピーする。

これを一発でコピーする方法を探しています(拡張機能なしで)

埋め込む


```yaml reference
https://github.com/gyarudev/napoancom/blob/main/cloudbuild.yaml
```

言語名の後にreferenceを付ける。

するとGitHubから中身が取得される。タイトル欄には、リポジトリのルートからのパスが自動で付けられる。

ドキュメントのビルド後も静的に書き出されず、読み込み時間が発生する。
つまり、レイアウトシフトが発生するので、ページの上の方に置くべきではない。

タイトルの上書き

タイトルを上書きしたい場合は、

```yaml reference title="aaa"

と書く。

お察しの通り、 Docusaurusのコードブロックはzennと微妙に記法が違う。 シンタックスハイライト自体はどちらもPrismなので変わらないが、タイトルに互換性がない。

GitHubリンクについて

See full example on GitHubのリンクは、埋め込んだURLと一致している。コミットハッシュ付きURLなら、リンク先も該当のコミットのものになる。

Discussion

ログインするとコメントできます