🦕

Docusaurusの編集用にVSCodeの拡張機能GitHubCopilotで作ってみた

に公開
VS Code
Docusaurus
GitHub Copilot
tech

はじめに

DocusaurusはMetaによって開発されたMarkdownをもとにドキュメントサイトを作成できるツールです。Reactベースで書かれているためデザインを変えたり別の機能を組み込んだりとかなり自由に使えます。

バージョン情報

  • VSCode v1.101.0
  • Node.js v22.12.0

どうしてこのツールを作るに至ったか

現在、Docusaurusで作成されたドキュメントサイトを組織内で利用しているが、

  • Markdownの書き方がわからない
  • コンフィグの書き方がよくわからない
  • カテゴリ新規作成が難しい

など、直接コードを触って設定したり、今まで触れてこなかった人にとっては謎の記法を使って記事を書かないといけなかったりと問題が出てきてしまいました

  • VSCodeのGitHubCopilotで記事の作成をしたい
  • VSCodeの優秀な構文ハイライト機能を使いたい

ここでそこまでVSCodeでの編集に固執しなくても、CMSを使ってWebでの編集でいいやんけという声がどこかから聞こえてきました。しかし生成AI需要を満たせる上にコーディング中にVSCodeで同じワークスペースにおいておけば勝手にドキュメント書いてくれるとかの需要があると判断しました。

実装した機能たち

  • Docusaurus独自のmarkdown記法のプレビュー
  • Docusaurus独自のmarkdown記法を含むテンプレートの挿入機能
  • 開いているドキュメントの文字数と行数、読むのにかかる時間のファイル統計機能
  • カテゴリの表示名と説明のGUI編集
  • Docusaurusの表示順に沿った独自のエクスプローラー
    • ブログとドキュメントの表示部分離
  • カテゴリ新規作成機能

指示した内容

# Docusaurusエディターの仕様書
Docusaurusのエディターを作ります

## markdownビューワ
- Docusaurusの独自記法に対応したMarkdownのビューワを作ってください
- ビューワはVSCode標準のMarkdownエディターに近い挙動をしてください
- 独自記法の中でも注釈の挙動に関しては注釈の種類に応じて絵文字と色を使って見分けがつくようにしてください

## Markdown記法の補完、挿入
- Docusaurus独自記法の補完に対応してください
- 右クリックメニューから見出しやリンクなどの基本的なMarkdown記法から、Docusaurus独自記法の挿入に対応してください

## エクスプローラ
- Docusaurus用のエクスプローラを用意します
- markdownファイルに書かれているsidebar_positionを参照して順番を入れ替えてください
- カテゴリの新規作成時に_category.jsonを作成し、設定を編集できるGUIを実装してください

## 文字・読了時間
- 文字数カウンタと読了時間の計測をして、VSCode右下の部分に表示してください

ロクに弄ってないエージェントモードを使ってみて

最初から適当に話してるとゴミを作ってくるのは対話型AIの時点でわかりきっていたので設計書を用意して提供した

copilot-instructions.mdの扱いはどうしてたの?

エージェントモードに入る前に普通のチャットモードである程度上の仕様書(と呼んでいいのかわからない何か)を作成し、エージェントモードに入った後、Claude Sonnet4に生成してもらいました

GitHub CopilotにおけるAIモデル所感

  • Claude

    • 極端に変なものを作り出さない代わりに設計がないとちょっと的外れなものを作ってくる
    • 指示さえしっかりして適宜要求すれば使える

  • ChatGPT

    • たまーにどうしてその思考に至ったか理解ができないものを提供してくるが、クオリティ自体は高い

今回のエージェントの書くコードの癖について

  1. 無断でMITライセンスを書いてくる
    どうしてそんなことしてくるのか理解はできないが、学習元の参照しているプロジェクトにMITライセンスのものが多い可能性がある。

  2. TypeScriptを使っているのにany型を多用してくる
    エージェントモードのAIが自分自身の書いたコードの型を忘れてそのエラー処理をしてもらったときに型を調べる前にanyにしたほうが簡単だという判断をした可能性?

  3. 定数をあまり作らない

  4. コードをフォルダで分けてくれない

  5. 機能ごとに分割するのが下手

  6. 非同期動作と同期動作の処理でawaitが必要なのに書かなかったりする

まとめ

  • エージェントモードは勝手に物を作ってくれる天才ではない。指示出してエラー内容を語り掛けることで初めて使える
  • コーディング規則にこだわりがなくても、手直しするときに読みにくいので追加する
GitHubで編集を提案

Discussion