Home

Appearance

GitHub Pages + VitePress環境セットアップ ​

セットアップ環境 ​

  • Windows11 PC
  • WSL2 Ubuntu
  • VScode
  • GitHub（無償版）

WSL2上でDockerが動作するようにしています。しかも、Docker CEをインストールしていてDocker Desktopを使っていません。 インストール方法を知りたい方は以下を参照してください。（実はこれが分かるまで結構時間がかかりました）

準備 ​

VitePressをインストールするにはGetting Startedに書いてある通りに進めれば問題ありません。 こちらの説明にあるようにNode.jsをインストールしておく必要があるのですが、いろいろバージョン問題などがありそうなので開発コンテナを用意して、 その中でセットアップすることにしました。

VitePressインストール ​

フォルダー構成 ​

ブログの記事はGitHubのリポジトリに置きますが、リポジトリのトップではなくdocsというフォルダーを作成して、その下に置く形にします。

インストール ​

以下のコマンドをリポジトリをクローンしたトップフォルダーで実行します。（docsフォルダーの下ではありません）

bash
npm add -D vitepress

セットアップ ​

こちらも説明通りに進めれば問題ありません。

bash
npx vitepress init

幾つか質問されますが、デフォルトのままで問題ありません。◇ Site title:や◇ Site description:は自分の考えたものを変えて良いです。

.gitignoreへの追加項目 ​

以下がgitで管理されないように.gitignoreに追記します。

node_modules
docs/.vitepress/dist
docs/.vitepress/cache

動作確認 ​

ローカルで動作確認をします。

bash
npm run docs:build

ビルドが通ったらプレビューを実行します。

bash
npm run docs:preview

GitHub Pagesの設定とデプロイ ​

GitHub Pagesにデプロイする場合にはGitHub Actionsでworkflowを動かします。ドキュメントをmainブランチで管理している場合、.ymlファイルも説明にあるdeploy.ymlがそのまま使えるので、.github/workflows/deploy.ymlを作成しておきます。

GitHub Pagesの設定 ​

GitHub Pagesの設定をします。[Settings]→[Pages]を開きます。Build and deploymentのSourceがDeploy from a branchであることを確認して、環境に従って変更します。 今回の環境ではdocsの下にドキュメントを配置しているため以下のようにしています。

Branch

Saveボタンで設定を保存したらインストールした内容一式をpushしてworkflowを動かしいます。（pushすると自動的に動き出します）workflowが問題なく動作完了するとGitHub PagesのHPが表示できるようになるので、以下のVisite siteをクリックして表示してみます。プレビューしたものとは全く違う見た目のものが表示されますが、それでOKです。

base設定の追加 ​

GitHubの無料版利用の場合、GitHubリポジトリをpublicに設定するしかなく、GitHub Pagesをprivateにすることはできません。その場合、.vitepress/config.mtsでbaseを設定する必要があります。base: '/<repository name>/'という形で設定します。例えばリポジトリ名がblogの場合には

ts
export default defineConfig({
  base: '/blog/',

という形で設定します。

GitHub Actionsを指定 ​

次にBuild and deploymentのSourceをGitHub Actionsに変更します。このあとに何らかのドキュメントファイルを編集することでworkflowを動かし、無事デプロイが完了するとローカルにプレビューしたものと同じものが表示されるようになります。