はじめに 🎯
皆さんは学習した内容をどこにまとめていますか？
NotionやObsidianを使う人が多いですが、プログラミング学習では「コードと一緒に記録を残すこと」 は非常に大事なことだと思います。それをポートフォリオとして、学習内容を見える化してみませんか？ 🚀
今回は、Astro のドキュメントサイト構築ツール 「Starlight」 を使って学習内容を公開しながら管理する方法をご紹介します。
なお、実際に作ってみたのが下記です。今回はDocs形式でまとめてみました。
👉 サイト: https://star-light-demo.vercel.app/
対象読者 👥
- 学習記録やナレッジを Notion/Obsidian 以外の方法で安全に管理したい と考えている方
- 学習記録を他の人に見せたい方 📢
- ナレッジを共有したい方 🤝
- コードを動かせる形で資産として残したいエンジニア 💻
- Node.jsがすでに入っている人
学習内容をどこにまとめる？ 🤔
多くの開発者が以下のツールで学習内容を管理しています：
- Notion 📝: データベース機能が豊富、チーム共有しやすい
- Obsidian 🔗: ローカル管理、リンク機能が強力
- Markdown ファイル 📄: シンプルで軽量
- Qiita/Zenn ✍️: 公開前提、フィードバックを得られる
しかし、個人的には「こうだったらな〜」と思う部分がありました。
どういう部分が物足りないか 😅
学習成果物の公開・共有のハードルが高い 🚧
- Notion: 有料プランでないと外部公開が制限される
- Obsidian: 静的サイト化するには別途設定が必要
検索性能の課題🔍
- 大量の学習記録が溜まると、目的のコードや情報を見つけるのに時間がかかる。
デザインや見やすさに限界がある 🎨
- Notion はテンプレートやテーマに制限があり、公開用ポートフォリオとして見栄えを整えるのが難しいです
- Obsidian は CSS でカスタマイズ可能
コードと文章の統合が難しい⚡
- Notion や Obsidian は文章とコードを一緒に書けますが、実際に動かせる形でコードを残すのは手間。学習記録として「試したコード＋結果＋解説」をセットで残すのが面倒
ここまではNotionやObsidianとの比較でしたが、ここからはQiitaやZennなどとも比較していきます。
Qiita・Zenn vs StarLight ⚖️
Starlightの優位性 🌟
-
高度な構造化と階層化
Starlightは、単なる記事の羅列ではなく、複数のセクションやサブセクションを持つドキュメントサイトを構築できます。 -
サイドバー:ナビゲーションが整理され、関連する学習内容をツリー構造で表示できます。 -
目次:ページの右側に自動で目次が生成され、長い記事でも特定のセクションに簡単にジャンプできます。 -
前後のページナビゲーション:ページ下部に「前のページ」「次のページ」へのリンクが自動生成され、学習の流れに沿ってスムーズに読み進められます。
これらは、QiitaやZennでも一部機能として存在しますが、Starlightではデフォルトでドキュメントサイトとして最適化されているため、手間なく高度な構造化を実現できます。
-
強力な検索機能🔍
StarlightはAlgolia DocSearchなどの検索エンジンと統合することで、全文検索機能を簡単に導入できます。これにより、大量のドキュメントの中から特定のキーワードを含むページを瞬時に見つけることが可能です。QiitaやZennの検索機能はプラットフォーム全体が対象となるため、自分の記事だけを効率的に探すのは難しい場合があります。 -
継続的な学習モチベーションの維持📈
サイトの成長 🌱: ページ数が増え、情報が整理されていく様子は、そのまま自分の成長の証となります
サイト自体の改善 ✨: スタイルやレイアウトをカスタマイズすることで、Web開発スキルを磨きながら、同時に学習記録を充実させることができます。これはQiitaやZennでは得られない体験です
サイト自体の改善: スタイルやレイアウトをカスタマイズすることで、Web開発スキルを磨きながら、同時に学習記録を充実させることができます。これはQiitaやZennでは得られない体験です。
-
自由度🎨
QiitaやZennは、記事のフォーマットやデザインがプラットフォームの規約に縛られます。一方、Astroは静的サイトジェネレーターであるため、デザインやレイアウト、機能追加に至るまで、すべてを自分の好きなようにカスタマイズできます。Web開発の学習記録であれば、その学習内容を活かしてサイト自体を改善していくことが可能です。これは学習意欲の向上にも繋がります。
-
ポートフォリオとしての活用💼
Astroで作成した学習記録サイトは、それ自体が成果物になります。GitHubでコードを管理し、Vercelなどにデプロイすれば、採用担当者に対して「この技術を使って、このようにアウトプットを出しました」と具体的に提示できます。QiitaやZennのプロフィールページよりも、技術力やデザインセンスをダイレクトにアピールする強力なポートフォリオになります。
-
依存関係の自己管理🛡️
QiitaやZennはプラットフォームの仕様変更に影響されますが、Astroは自分で構築するため、長期的なメンテナンスの見通しが立てやすいです。Starlightを使えば、依存関係はシンプルに保たれ、今後の技術トレンドの変化にも柔軟に対応できます。これは、開発者としての経験値にもなります。
-
高いパフォーマンスとSEO⚡
AstroはデフォルトでJavaScriptを最小限に抑えるように設計されているため、ページの読み込み速度が非常に高速です。これはユーザー体験を向上させるだけでなく、Googleなどの検索エンジンからも高く評価されるため、SEOに強いというメリットもあります。
※ここまで、StarLight贔屓で紹介してきましたが、QiitaやZennなどと比較すると下記のデメリットもあります。
ここらへんはアウトプット先を適宜使い分けるなどして恩恵を享受するとよいです。
Qiita・Zennと比較したトレードオフ⚠️
QiitaやZennのように「いいね」や「ストック」、コメントといった他者からの直接的なフィードバックは得られません。新しい技術記事を書いた際に多くの人に読んでもらうという集客力も、基本的には自分でSEO対策などをする必要があります。
構築の手間⏳
サイト構築からデプロイまで、初期設定にある程度の学習コストがかかります。QiitaやZennのようにアカウント作成後すぐ執筆を始められる手軽さはありません。（ただし、微々たる差だと考えております。）
比較表
| 項目 | Starlight | Notion | Obsidian | Qiita / Zenn |
|---|---|---|---|---|
| クラウド依存 | Git管理 | クラウド依存 | ローカル管理 | クラウド依存 |
| コードとの統合性 | ★★★★☆ (コードブロックの可読性) | ★★☆☆☆ (メモ向け) | ★★★★☆ (シンタックスハイライト) | ★★★★☆ (シンタックスハイライト) |
| 公開・共有のしやすさ | ★★★★☆ (デプロイが簡単) | ★★☆☆☆ (有料プランが必要) | ★☆☆☆☆ (別途設定が必要) | ★★★★★ (即座に公開) |
| 検索性能 | ★★★★☆ (全文検索導入可) | ★★★★★ (高速) | ★★★★★ (高速) | ★★★★☆ (プラットフォーム全体) |
| 学習コスト | ★★★☆☆ (MarkdownとAstro) | ★★★★★ (直感的) | ★★☆☆☆ (慣れが必要) | ★★★★★ (即座に執筆可) |
| カスタマイズ性 | ★★★★★ (Web開発の知識を活かせる) | ★★☆☆☆ (テンプレートに依存) | ★★★★☆ (CSSカスタマイズ) | ★★☆☆☆ (制限あり) |
| コスト | ★★★★★ (無料) | ★★☆☆☆ (個人利用は無料) | ★★★★★ (無料) | ★★★★★ (無料) |
| コミュニティ | ★☆☆☆☆ (なし) | ★★★★☆ (チーム共有) | ★☆☆☆☆ (なし) | ★★★★★ (いいね/ストック) |
| ポートフォリオ | ★★★★★ (サイト自体が成果物) | ★★☆☆☆ (見せ方に限界) | ★☆☆☆☆ (非公開前提) | ★★★☆☆ (プロフィールページ) |
ここまで、StarLightを紹介してきましたが、Astroというフレームワークの中のツールを使用しております。この、ドキュメントサイトの利用をツールのStarLightを使用して、より高速に作成していきます。
Astro でできること
-
ブログ・ポートフォリオサイト: 静的サイト生成の強みを活かし、超高速なブログやポートフォリオサイトを構築できます。
-
ドキュメントサイト: Starlight と呼ばれる公式のフレームワークを使えば、プロフェッショナルなドキュメントサイトを簡単に作成できます。
-
ECサイト・ランディングページ: JavaScriptを最小限に抑えることで、商品の表示速度を上げ、コンバージョン率を高められます。
Starlightとは？
Astro製のドキュメントサイト構築ツールです。中でもこのような特徴を持ってます。
- Markdown ベース: 学習内容をそのまま Markdown で書けばサイトになる
- コードに最適化: シンタックスハイライト、コピーボタンが標準搭載
- 検索機能内蔵: 全文検索で過去の学習内容をすぐに見つけられる
- レスポンシブ対応: スマホからでも学習記録を確認可能
そのため、.mdや.mdxの記述経験があれば移行コストはかかりません。
（おそらくこの記事を見ている人は大丈夫かと思います。）
環境構築
ここからは環境構築です。
といってもNode.jsが入って入れば直ぐにできます。（入れてない人は下記を参考にしてください。）
>npm create astro@latest -- --template starlight # 左記を打鍵
# 下記のように表示が出ます。
#> npx
#> create-astro --template starlight
#astro Launch sequence initiated.
#╭─────╮ Houston:
#│ ◠ ◡ ◠ Awaiting further instructions.
#╰─────╯
# astro Launch sequence initiated.
dir Where should we create your new project?
sample-pj # ここで、Pj名を決めます。
Yes
git Initialize a new git repository? # yes
Yes
# ██████ Project initializing...
# ▶ Template copying...
# □ Dependencies
# □ Git
# next Liftoff confirmed. Explore your project!
# Enter your project directory using cd ./sample-pj
# 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! 🚀
#╰─────╯
下記でPjが作成されます。起動して見ましょう。
cd sample-pj
npm run dev # localhost:4321で起動
このような画面が出てきたら環境構築は終了です！非常に簡単ですね👍️
StarLightのフォルダ構成
ここからは、カスタマイズ方法の紹介になります。
フォルダ構成は下記の通りです。基本的には、下記の２ファイルを新規作成・編集すれば問題ないです。
src/contents/docs/*
astro.config.mjs
sample-pj/
├── .astro/
├── .devcontainer/
├── .vscode/
├── node_modules/
├── public/
│ └── favicon.svg
├── src/
│ ├── assets/
│ │ └── logo.svg
│ ├── content/
│ │ ├── docs/ # Routing対象
│ │ │ ├── index.mdx # LP
│ │ │ └── guides/ # /localhost:4321/guidesのroutingになる。
│ │ │ ├── 01_environment.md # 実際の記事(htmlに変換される。)
│ │ │ └── 02_basic.md # 実際の記事(htmlに変換される。)
│ │ └── config.ts
│ └── env.d.ts
├── astro.config.mjs # カスタマイズ
├── package.json
├── tsconfig.json
└── README.md
記事の作成方法
src/content/docsフォルダにmdxファイルを追加するだけで新しいページが作成されます。
サンプルで、sample.mdxを作成してみましょう。下記の通りになります。
content/docs/
├── guides/
│ └── example.md
├── reference/
└── sample/ # 新規で作成
└── sample.mdx # 新規で作成
次に、Astroに、追加したSampleのRoutingを認識させます。
下記ファイルに、追加部分を記述します。
<!-- astro.config.mjs -->
// @ts-check
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
// https://astro.build/config
export default defineConfig({
integrations: [
starlight({
title: 'My Docs',
social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/withastro/starlight' }],
sidebar: [
{
label: 'Guides',
items: [
// Each item here is one entry in the navigation menu.
{ label: 'Example Guide', slug: 'guides/example' },
],
},
{
label: 'Reference',
autogenerate: { directory: 'reference' },
},
// --- 以下を追加することで、パンくずリストを追加できます。------------
{
label: 'Sample', // パンくずリストの名称をここで決めます。
autogenerate: { directory: 'sample' }, // 定義したディレクトリの内容をRouotingとして設定します。
},
// --- ここまで -----------------------------------------------
],
}),
],
});
そして、作成したsample.mdxに下記をコピペします。
---
title: "Astro とは"
label: "StarLightガイド"
---
## Astro とは
Astro は、コンテンツ駆動型のウェブサイトを構築するためのモダンなウェブフレームワークです。静的サイト生成（SSG）を主な得意分野とし、ブログ、マーケティングサイト、ドキュメントサイトなどに最適です。特に、JavaScriptを最小限に抑えることで、非常に高速なウェブサイトを生成できるのが最大の特徴です。
### Astro の主な機能と特徴
1. **コンテンツファースト ✍️**
Astro はコンテンツを最優先に設計されています。Markdown、MDX、そしてAstroコンポーネントを使って、直感的にコンテンツを作成できます。
2. **JavaScript ゼロの理念 🚀**
デフォルトでは、Astro はクライアントサイドに JavaScript を送りません。これにより、ウェブサイトの読み込み速度が大幅に向上し、パフォーマンスとSEOに大きなメリットをもたらします。
3. **アイランドアーキテクチャ 🏝️**
インタラクティブなコンポーネントが必要な場合、Astro はその部分だけを個別の「アイランド」として分離し、JavaScriptを最小限にロードします。これにより、ページ全体がJavaScriptに依存するのを防ぎます。
4. **UIフレームワークのサポート 🧩**
React, Vue, Svelte, SolidJS など、お好みの UI フレームワークのコンポーネントを Astro プロジェクト内でシームレスに利用できます。
5. **サーバーサイドレンダリング (SSR) 🖥️**
静的サイト生成だけでなく、SSRにも対応しています。これにより、ユーザーごとにパーソナライズされたコンテンツや、リアルタイムなデータを含むページを生成できます。
### Astro コンポーネントの基本
Astro のUIは、`.astro`拡張子のコンポーネントを使って構築されます。
- **コンポーネントスクリプト**: `---` で囲まれた部分に JavaScript/TypeScript を記述します。データの受け渡しや外部APIからのデータ取得など、ページのロジックを担当します。
- **コンポーネントテンプレート**: スクリプト部分の下に、HTMLやJSXライクな構文でUIを記述します。
- **コンポーネントスタイル**: `<style>` タグで CSS を記述します。デフォルトでスコープ化されるため、他のコンポーネントに影響を与えません。
#### コンポーネントの例
```astro
---
// Propsとしてタイトルを受け取ります
const { title } = Astro.props;
---
<h1>{title}</h1>
<style>
h1 {
color: #333;
}
</style>
少しコードを解説すると、
---
title: "Astro とは"
label: "StarLightガイド"
---
こちらは、フロントマターと呼ばれるものになります。簡単にいえば、htmlのheaderタグと同様の扱いであり、OGPをここで設定することができます。
コピペできたら、こちらを確認してみましょう。
http://localhost:4321/sample/sample
無事作成することができました！また、無事に左のパンくずが反映されていますね。
また、こちらを見てもらえばわかる通り、基本的にフォーマットやパンくず自体も整理されております。（レスポンシブ対応も既存でできてます。）
※iPhoneでもきれいに反映されていますね✨️
htmlやcssがあまりわからない！という方でもきれいに管理しやすいと思います。
このようにmdxファイルを作成していくことで、簡単に自分のPFを作成していくことができます！
まとめ
Starlight は「コードを残しながら学習を整理」できる強力な選択肢です。
Starlightの強み
-
学習記録がそのまま資産になる: きれいにフォーマットされたコードとドキュメントは、後から見返しても理解しやすいため、あなたの財産になります。
-
公開すればポートフォリオにもなる: 学習過程自体がアウトプットとなるため、あなたの技術力を具体的に示すポートフォリオとして活用できます。
-
長期運用に安心: シンプルな依存関係とGitでのバージョン管理により、長期的なメンテナンスも容易です。
-
検索性能が高い: パンくずリストや、サイト内検索が標準で備わっているため、蓄積した大量の学習記録から必要な情報を素早く見つけ出せます。
最後に、こちらAstroで作成したDocsのGithubです。
👉 今回作成したGithub:
https://github.com/iijima-naoya-45b/starLightDemo
参考リンク
Astro Starlight:
https://starlight.astro.build/ja/?utm_source=chatgpt.com
Astro:
https://astro.build/?utm_source=chatgpt.com
Vercel:
https://docs.astro.build/ja/guides/deploy/vercel/?utm_source=chatgpt.com