📝

VitePressとCloudflare Pagesで爆速で技術文書を公開する

kira

2024/08/16に公開

はじめに

VitePressは技術文書の作成に適した静的サイトジェネレータです。この記事ではVitePressを使用して文書を作成し、それをCloudflare Pagesにデプロイする手順をステップバイステップ形式で紹介します。成果物は以下のURLから閲覧することが出来ます。

https://snip.kira924age.com

VitePressとは?

VitePressはVue製の静的サイトジェネレータです。
このツールはVuePressの精神的な後継者と位置付けられており、洗練されたデザインと高いパフォーマンスが特徴です。

多くの静的サイトジェネレータがそうであるようにMarkdown形式で書かれたファイルからウェブページのコンテンツを生成できます。

Cloudflare Pagesとは?

Cloudflare PagesはCloudflareが提供する静的サイトホスティングサービスです。このサービスは自動ビルド・デプロイ機能やプレビュー環境の自動作成機能を備えており、迅速かつ簡単にウェブサイトの公開を実現できます。

無料プランでは、月あたりのビルド回数や設定できるカスタムドメインの数に有料プランよりも厳しい制限がありますが、基本的な機能に制限はありません。
今回はCloudflare Pagesの無料プランを利用します。

VitePressでの文書作成

以下の手順でVitePressを使用して文書を作成することができます。

1. プロジェクトの準備

まずローカル環境に作業用のディレクトリを作成します。今回のプロジェクト名を「code-snippets」と定めたので、以下のコマンドを使ってcode-snippetsディレクトリを作り、その中に移動します。

$ mkdir code-snippets
$ cd code-snippets

さらに今回はモノレポ構成を採用するため、docsサブディレクトリを作成し、VitePressプロジェクトはそのディレクトリ内に配置します。以下のコマンドを実行してdocsディレクトリを作成して移動します。

$ mkdir docs
$ cd docs

公式ドキュメントによるとVitePressのインストールにはNode.jsのバージョン18以上が必要なようです。

今回はNode.jsのバージョン20をVoltaを利用してインストールしました。

$ volta install node@20

2. VitePressのインストールおよびセットアップ

以下のコマンドでVitePressをインストールします。

$ npm add -D vitepress

インストール後、VitePressに含まれるセットアップウィザードを実行して、プロジェクトの初期設定を行います。以下のコマンドを実行します。

$ npx vitepress init

このコマンドを実行すると、対話形式で必要なプロジェクト構成情報を尋ねられます。

この時点でのdocs以下のディレクトリ構成は以下のとおりです。

$ tree -L 2 -aI 'node_modules'
.
├── .vitepress
│   ├── cache
│   └── config.mts
├── api-examples.md
├── index.md
├── markdown-examples.md
├── package-lock.json
└── package.json

3 directories, 6 files

npx vitepress initコマンドを実行した後、api-examples.md、index.md、markdown-examples.md の3つのMarkdownファイルが作成されていることを確認できます。

package.jsonファイルを見ると以下のようにnpm scriptsの設定が追加されていることが確認できます。

$ cat package.json
{
  "devDependencies": {
    "vitepress": "^1.3.2"
  },
  "scripts": {
    "docs:dev": "vitepress dev",
    "docs:build": "vitepress build",
    "docs:preview": "vitepress preview"
  }
}

npm run docs:devで開発サーバーを起動できます。ブラウザからアクセスすると以下のようなページが表示されます。

3. configの設定と文書の追加

api-examples.md, markdown-examples.mdを削除してindex.mdを編集しWebページの内容を記載したMarkdownファイルを追加します。

次にプロジェクトの設定ファイル.vitepress/config.mtsを編集してサイトをカスタマイズします。
以下のようにnav, sidebar, socialLinksを変更しました。

$ cat .vitepress/config.mts
import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
  title: "Code snippets",
  description: "code snippets for competition",
  themeConfig: {
    // https://vitepress.dev/reference/default-theme-config
    nav: [
      { text: 'About', link: '/about' }
    ],

    sidebar: [
      {
        text: '整数論',
        items: [
          { text: '素因数分解', link: '/number_theory/prime_factorization' }
        ]
      },
      {
        text: 'グラフ理論',
        items: [
          { text: '巡回セールスマン問題', link: 'graph/traveling_salesman_problem' },
          { text: 'ダイクストラ法', link: '/graph/dijkstra' }
        ]
      },
      {
        text: 'データ構造',
        items: [
          { text: 'Union Find Tree', link: '/data_structure/union_find' }
        ]
      },
      {
        text: '暗号',
        items: [
          { text: 'シーザー暗号', link: '/crypto/caesar_cipher' }
        ]
      },
      {
        text: 'その他',
        items: [
          { text: '座標圧縮', link: '/other/shrink_coordinate' }
        ]
      },
    ],

    socialLinks: [
      { icon: 'github', link: 'https://github.com/kira924age/code-snippets' }
    ]
  }
})

4. 数式の描画

今回は数式の描画をしたいため、markdown-it-mathjax3をインストールし、configのmarkdown.mathオプションをtrueに変更します。

npm add -D markdown-it-mathjax3

// .vitepress/config.mts
  export default defineConfig({
    title: "Code snippets",
    description: "code snippets for competition",
    markdown: {
      math: true
    },
  ...

gitの設定

GitHubに新しいレポジトリを作成しローカルの内容をプッシュします。

1. GitHubリポジトリの作成

GitHubにログインしダッシュボードから新しいリポジトリを作成します。

2. gitignoreファイルの追加

ローカル環境のdocsディレクトリ内に.gitignoreファイルを新規作成します。
これにより指定したファイル・ディレクトリをGitの追跡から除外することができます。

$ cat .gitignore
node_modules/
.vitepress/dist/
.vitepress/cache/

3. gitリポジトリの設定

ローカルのプロジェクトのルートディレクトリに移動しgitレポジトリを初期化します。

$ cd ..
$ git init

ローカル環境のファイルをGitで追跡し、変更をコミットします。これにより、プロジェクトの現在の状態がGitの履歴に保存されます。

$ git add .
$ git commit -m "Initial commit"

メインブランチを設定し、GitHub上に新しく作成したリモートリポジトリにプロジェクトをプッシュします。

$ git branch -M main
$ git remote add origin git@github.com:kira924age/code-snippets.git
$ git push -u origin main

Cloudflare Pagesの設定

Cloudflareにログインし、ダッシュボードのサイドバーからWorkers & Pages > 作成 > Pagesに進み、Gitに接続ボタンをクリックします。

先程作成したGitHubリポジトリを選択してセットアップの開始ボタンをクリックします。
その次に以下の内容を入力して保存してデプロイするボタンをクリックします。

プロジェクト名: code-snippets
プロダクションブランチ: main
フレームワークプリセット: VitePress
ビルドコマンド: npx vitepress build
ビルド出力ディレクトリ: .vitepress/dist
ルートディレクトリパス: docs
環境変数
- 変数名: NODE_VERSION
- 値: 20.16.0

この設定により、GitHubリポジトリにプッシュされるたびにCloudflareが自動的にビルドとデプロイを行うようになります。

Cloudflare Pagesを使用してデプロイしたプロジェクトは、デフォルトで.pages.devドメイン下にホストされます。

https://code-snippets.pages.dev/

カスタムドメインの設定もダッシュボードから簡単に行えます。詳しくは公式ドキュメントを参照してください。

https://snip.kira924age.com/

おわりに

この記事ではVitePressを利用して技術文書を作成しCloudflare Pagesでデプロイする方法を紹介しました。プロジェクトのセットアップからコンテンツの作成、GitとGitHubを使ったバージョン管理、そして最終的な公開までの全過程をステップバイステップで解説しました。
良さそうと思われたら是非試してみてください。

UrthPublication

株式会社Urthのテックブログです。日々の業務で役立ちそうな内容を皆さんに共有していきます。