🌟

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

2021/11/09に公開約1,700字

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/sasigume/napoancom/blob/main/cloudbuild.yaml
```

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

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

タイトルの上書き

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

```yaml reference title="aaa"

と書く。

GitHubリンクについて

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

Discussion

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