Zenn
🚀

Starlightに入門して自分の使いやすいドキュメントホスティングサイトを爆速で構築してみる

2023/09/04に公開
tech

astroだけでも簡単にドキュメントサイトやブログなど簡単に作れて楽しいのですが、それをさらに効率化するドキュメントサイトを作ることに特化したフレームワークであるStarlightがあります。

最近tailwindでのカスタムテーマの追加のexampleが追加されたり Astro 3.0がリリースされたりと盛り上がってきていたので、色々と触ってみていい感じにかっこいいドキュメントサイトを爆速で構築してみます。

以前 Astroでポートフォリオサイト作ったりもしているので、そのポートフォリオサイトの説明みたいなページを作っていきます。

https://zenn.dev/okojomoeko/articles/astro-portfolio

今回試した環境

  • MacBook Air M1
  • npm: 9.8.1
  • node: v18.16.0
  • vs code: 1.81.1

早速作っていく

まだまだBetaで進化中であるStarlightですが、公式サイトのドキュメントはなんと日本語にも対応しているので、これに従って進めていきます。

プロジェクトを作って確認する

公式に従って下記コマンドでcreate astroします。

➜ npm create astro@latest -- --template starlight/tailwind

╭─────╮  Houston:
│ ◠ ◡ ◠  Let's create something unique!
╰─────╯

 astro   v3.0.7 Launch sequence initiated.

   dir   Where should we create your new project?
         ./starlight-tailwind-doc
      ◼  tmpl Using starlight/tailwind as project template
      ✔  Template copied

  deps   Install dependencies?
         Yes
      ✔  Dependencies installed

    ts   Do you plan to write TypeScript?
         Yes

   use   How strict should TypeScript be?
         Strict
      ✔  TypeScript customized

   git   Initialize a new git repository?
         Yes
      ✔  Git initialized

  next   Liftoff confirmed. Explore your project!

         Enter your project directory using cd ./starlight-tailwind-doc
         Run npm run dev to start the dev server. CTRL+C to stop.
         Add frameworks like react or tailwind using astro add.

         Stuck? Join us at https://astro.build/chat

╭─────╮  Houston:
│ ◠ ◡ ◠  Good luck out there, astronaut! 🚀
╰─────╯

まずはデフォルトでその美しさを確認します。

➜ cd starlight-tailwind-doc;
❯ npm run dev

> starlight-tailwind-doc@0.0.1 dev
> astro dev

  🚀  astro  v3.0.7 started in 493ms

  ┃ Local    http://localhost:4321/
  ┃ Network  use --host to expose

06:35:55 PM [content] Watching src/content/ for changes
06:35:56 PM [content] The "i18n" collection does not have an associated folder in your `content` directory. Make sure the folder exists, or check your content config for typos.
06:35:56 PM [content] Types generated
06:35:56 PM [astro] update /.astro/types.d.ts

最初の画面
最初の画面

はい、僕はこれを見た瞬間に恋に落ちました。かっこいいです。darkとlight両方のテーマが扱えるポイントもグッドです。

ここまでで5分くらいでしょうか。

実際にそれっぽいドキュメントを作っておいてみる

example.mdが置いてあるので、それに従ってサンプルのドキュメントを追加します。

今回は下記の内容を追加してみます。

---
title: ポートフォリオサイトについて
description: Astroで構築されたポートフォリオサイトの説明
---

## 構成

下記の構成で自分について説明していく。

- 簡単な経歴
    - 学歴
    - 職歴
- 資格
- スキル
- なんか作ったものがあれば

### プロジェクト

自分の成果物はプロジェクトとして書く

- [プロジェクト1]
- [プロジェクト2]

ドキュメント書くときにtitleのfrontmatterは必要です。

この内容を一旦referenceディレクトリの下に置いてみますと、いい感じにサイトが更新されて内容が出てきました！

適当なドキュメント
ドキュメントを配置してみる

一旦referenceディレクトリの下に置いたのは、templateではreference配下のmarkdownファイルは自動的にslugが生成されてURLでアクセスできるようになるからです（今回だと/reference/site-structure/が生成されてます）。

sidebarの設定はastro.config.mjsで細かく何を表示させるかを決めることができますが、爆速で構築するならautogenerateが無難かなと思います。

ただし、日本語とかが混じってしまうとなかなかカオスなURLになるので、autogenerateでガシガシドキュメント書いていくならなるべくディレクトリやファイル名を英語で統一したほうが無難です。

以下の例では、日本語のドキュメントファイル名だったり、フォルダ名に日本語を途中で使ってしまったときのURLとドキュメントサイトの構造を示しています。


日本語のディレクトリや日本語のファイル名での表示例

  • 日本語ファイル名: reference/projects/プロジェクト1.md
    • エンコード前: http://localhost:4321/reference/projects/プロジェクト1/
    • URL: http://localhost:4321/reference/%E3%83%97%E3%83%AD%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%881/
  • 日本語ディレクトリと英語ファイル名混ぜ合わせ
    • エンコード前: http://localhost:4321/reference/projects/プロジェクト1詳細について/project1-detaild/
    • URL: http://localhost:4321/reference/projects/%E3%83%97%E3%83%AD%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%881%E8%A9%B3%E7%B4%B0%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6/project1-detaild/

他に気になった機能を確認してみる

何度も言いますが、爆速を目指すので最低限の自分が気になった機能だけの確認にとどめたいと思います。

気になった機能としては下記の点になるので、それぞれ試してみたり機能を追加してみたりします。

目次を細かくしたい

デフォルトではtable of contentsのheading levelが
最小で2、最大で3レベルまでが表示されますが、astro.config.mjsからグローバルに設定したりページごとに細かい目次まで表示させることもできます。

下記site-structure.mdのドキュメントだけfrontmatterにtocのlevelを最小2、最大5に設定して細かく目次を表示させたときの例です。


目次を細かくしてみた

multi language対応

多言語でのドキュメントについても、適当に多言語用のディレクトリ作ってドキュメントをぶち込むだけで簡単に対応できてしまいます。

astro.config.mjsに下記のlocale設定を追加して。。。

astro.config.mjs
// https://astro.build/config
export default defineConfig({
  integrations: [
    starlight({
   title: "Docs with Tailwind",
+    defaultLocale: "ja",
+    locales: {
+     en: {
+      label: "English"
+     },
+     ja: {
+      label: "日本語"
+     },
+     fr: {
+       label: "Français",
+     },
+    },
.
.

各locale専用のドキュメントを用意します（ここであえてフランス語は入れてません）。

└── docs
    ├── en
    │   ├── guides
    │   │   └── example.md
    │   ├── index.mdx
    │   └── reference
    │       ├── example.md
    │       ├── projects
    │       │   ├── About Project1
    │       │   └── プロジェクト1.md
    │       └── site-structure.md
    ├── index.mdx
    └── ja
        ├── guides
        │   └── example.md
        ├── index.mdx
        └── reference
            ├── example.md
            ├── projects
            │   ├── About Project1
            │   └── プロジェクト1.md
            └── site-structure.md

結果として、日本語だとこんな感じに。


日本語バージョンのページ

英語を選択するこんな感じになります。


英語バージョンのページ

また、defaultLocale: "ja"を設定しているので、仮に対応していないフランス語を選択した場合でも、各言語でこのコンテンツにはまだ◯◯語訳がありませんって自動で表示される親切設計です。


フランス語バージョンでまだ未対応のページ(デフォルトでja)

上記の中でUIとなる部分の表示言語はフランス語になっているのも良いですね。

wikilinkとかで参照を爆速にしたい

astroはpluginを使って機能を拡張できます。

やっぱり爆速にリンクとかを生成するならwikilinkとか使って書きたいなと思ったので、公式で紹介されているawesome-remarkのプラグインリストだったりとか誰かが作成してくれたいい感じのpluginを使わせていただきます。

すでにpublic archiveになってしまっていますが、こちらのやつが良さそうだったので導入してみます。

npm i remark-wiki-link-plusで導入して、astro.config.mjsにpluginの設定を追加します。

astro.config.mjs
+import wikiLinkPlugin from "remark-wiki-link-plus";
export default defineConfig({
  integrations: [
  ],
  image: {
  },
+  markdown: {
+    remarkPlugins: [
+      [
+        wikiLinkPlugin,
+        {
+          markdownFolder: `src/content/docs`,
+        },
+      ],
+    ],
+  },
});

後は適当にwikilink入れてみたら爆速でリンク生成できました。


wikilinkによるリンクの生成

mermaidとか使いたい

直前のgifでmermaid使えることが見えていますが。。。

デフォルトではこの機能自体は今のところついていませんが、根っこはastroなのでpluginだったり、scriptを読み込んでしまえばでなんでもできます。

今回は、Astroの作品例で公開されているhello-astroという作品を参考に、この中でmermaidを使った自作pluginを作られているみたいなので、こちらを拝借させていただきました。

上記のリポジトリを参考に、必要なところだけ下記の様に切り出して、remark-pluginsの中にpluginとして作って入れておきます。

remark-diagram.mjs
import { visit } from "unist-util-visit";

export function remarkDiagram() {
  return function (tree, { data }) {
    visit(tree, "code", (node) => {
      if (node.lang == "mermaid") {
        node.type = "html";
        node.value = '<div class ="' + node.lang + '">' + node.value + "</div>";
      }
    });
  };
}

astro.config.mjsにpluginの設定を追加します。

astro.config.mjs
+import { remarkDiagram } from "./remark-plugins/remark-diagram.mjs";
export default defineConfig({
  integrations: [
  ],
  image: {

  },
+  markdown: {
+    remarkPlugins: [remarkDiagram],
+  },
});

pluginはできたので、後はちゃんとmermaidをレンダリングするライブラリを入れるわけですが、今回はmermaidをレンダリングするページだけCDNから読み込んで使うようにします。

生でastro使うのであれば、ページを構成するベースとなるLayoutコンポーネントとかで読み込ませるのでしょうが、starlightのフレームワークを使っているので、あまり直接コンポーネントとかastroの知識がなくても追加で色々設定できるようにしたいのです。

ということで、starlightではfrontmatterのheadに色々定義できるので、scriptタグで読み込むようにします。

astro.config.mjs
export default defineConfig({
  integrations: [
    starlight({
+      head: [
+        {
+          tag: "script",
+          attrs: {
+            src: "https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"
+          }
+        }
+      ]
    }),
  ],

});

これでmermaidがドキュメントで使えるようになりました！


mermaidが表示された

が、下記のようにライトテーマとダークテーマでmermaidの描画テーマが変わりません。


ダーク/ライトでmermaidが変わらない

そこで、starlightのテーマにしたがって、mermaidを読み込むときにテーマが変わるようにさらにscriptを追加しておきます。

astro.config.mjs
export default defineConfig({
  integrations: [
    starlight({
      head: [
        {
          tag: "script",
          attrs: {
            src: "https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"
          }
        }
      ],
+      {
+        tag: "script",
+        content:
+          '(() => { const storedTheme = typeof localStorage !== "undefined" && localStorage.getItem("starlight-theme"); mermaid.initialize({ startOnLoad: true, theme: storedTheme }); })();',
+      },
    }),
  ],

});

これでページが読み込まれていたときに設定していたテーマでmermaidのテーマも変わるようになります。

ただ、mermaidのページが読み込まれないと(mermaidを扱うページでテーマ変更しても)テーマが変わるわけではないので、テーマをreactiveに変えることができないのが少し残念です。まぁ最低限使えるようにしたので許してください（他にやり方あればぜひご教授お願いします！）。

所感とまとめ

ここまでの完成品を下記においておきます。

https://github.com/okojomoeko/starlight-tailwind-doc

下記気になったところを少しメモっておきます。

  • 日本語の検索はちょっと微妙？
    • 検索にpagefindというライブラリを使っていそうだけど、もっとfuzzyな検索がしたいかも
  • reactiveに動かせるところがすくない？
    • mermaidのテーマとかそうですが、リアクティブにゴリゴリするものも色々試してみたい？

自分自身はなにかドキュメントをゴリゴリ書いていくということは少ないかもしれないですが、Docusaurusとかmkdocsとか結構競合がいる中で頑張って伸びていってくれると信じてなるべくこれを使っていくようにしたいと思います！

また、コミュニティプラグインもあるようなのでこれからの進化がすごく楽しみになりました！以上！

https://starlight.astro.build/showcase/#community-plugins

Discussion