はじめに

目的

Markdownは、変更履歴の管理も容易でブログやドキュメントの作成に適しています。
生成AIと相性が良いMarkdownを使ってドキュメントを作成・管理することは、開発には勿論のこと様々な場面で便利かと思います。

今回はVitePress を使ってMarkdownで作成した記事を公開し、共有する方法を紹介します。

今回の手順で作成したサンプルページは以下のリンクから確認できます。
サンプルページ

対象読者

• VitePress を使ってブログやWebサイトを開発したい方
• GitHub Pages を使ってブログを公開したい方

前提条件

今回の手順を実行するには以下の準備が必要になります。

• Node.js のインストールが完了していること
• GitHub アカウントを持っていること

VitePress とは

VitePress は Vue3 と Vite を使用して開発されている静的サイトジェネレーターです。静的サイトとして公開されるので、高速で軽快に動作します。

Markdown で記事を作成すれば、直ぐにページを公開できるのも魅力です。ページは、Vue コンポーネントを使用してカスタマイズすることも可能です。

ブログを開発する

VitePressを使ってローカル環境でページを表示してみます。

以下のバージョンで動作確認しています。

Node.js: 22.13.1
VitePress: 1.6.3

インストール

はじめにVitePress をインストールします。 VitePressは、Node.js のバージョン 18 以上が必要です。

Node.js のバージョンを確認します。

node -v
// v22.13.1

バージョンが 18 未満の場合は、Node.js のバージョンをアップデートしてください。
Node.jsがインストールされていない場合は、Node.js のインストールを参考にしてください。

Node.js のバージョンに問題なければ、VitePress をインストールします。
以下のコマンドを実行して、VitePress をインストールします。

npm add -D vitepress

VitePressのインストールが完了すると、node_modules ディレクトリと package.json, package-lock.json が作成されます。

├── node_modules
├── package-lock.json
└── package.json

次に、VitePress のプロジェクトを初期化（作成）します。
以下のコマンドを実行して、プロジェクトを初期化します。

npx vitepress init

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?(srcに相当するディレクトリが設定できます。)
│  ./docs
│
◇  Site title:(サイトのタイトルを設定できます。後から変更可能)
│  My Sample Blog
│
◇  Site description:(サイトのdescriptionを設定できます。後から変更可能)
│  this is sample blog page.
│
◇  Theme:(テーマを選択できます。後からテーマカスタマイズ可能)
│  Default Theme
│
◇  Use TypeScript for config and theme files?(TypeScriptを使う場合は、Yesを選択)
│  Yes
│
◇  Add VitePress npm scripts to package.json?(自動でスクリプトを追加する場合は、Yesを選択)
│  Yes
│
└  Done! Now run npm run docs:dev and start writing.

初期化が完了すると、以下のようなファイルが作成されます。（docsは初期化時の質問で回答したディレクトリ名です。）

├──docs
│   ├── .vitepress
│   │   └── config.mts
│   ├── api-examples.md
│   ├── index.md
│   └── markdown-examples.md
├── node_modules
├── package-lock.json
└── package.json

VitePress のローカルサーバーを起動して、ページ表示を確認します。

以下のコマンドを実行して、ローカルサーバーを起動します。

npm run docs:dev

コマンドラインに表示される http://localhost:5174/ にアクセスすると、ページが表示されます。

> docs:dev
> vitepress dev docs

Port 5173 is in use, trying another one...

  vitepress v1.6.3

  ➜  Local:   http://localhost:5174/
  ➜  Network: use --host to expose
  ➜  press h to show help

GitHub Pages に公開する

VitePress で作成したページを GitHub Pages に公開してみます。

GitHub Pages に公開するためには、以下の手順が必要です。

1. レポジトリのメニューからGitHub Pages で公開するための設定を行う
2. GitHub Actions で自動デプロイするためのワークフローファイルを作成する

GitHub Pages

パブリックなレポジトリであれば、GitHub Pages を使って無料で静的サイトを公開できます。
ソースコードを非公開にしたい場合は、別途有料のアカウントにアップグレードするか、別のホスティングサービスを検討する必要があります。

GitHub Pages の公開設定

まずGitHubのレポジトリメニューから、Settings を選択します。

Settings 画面の左メニューから、Pages を選択します。

ビルドとデプロイをGitHub Actions で行うため、以下のプルダウンからGitHub Actions を選択します。

GitHub Actions で自動デプロイする

次にGitHub Actions で自動デプロイするためのワークフローファイルを作成します。

.github/workflows ディレクトリを新規に作成し、deploy.yamlを作成します。
このワークフローファイルは、main ブランチに push されたときに、VitePress のビルドを行い、GitHub Pages にデプロイするまでを自動化します。

# .github/workflows/deploy.yaml
name: Deploy VitePress site to Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22.x
          cache: npm
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Install dependencies
        run: npm ci
      - name: Build with VitePress
        run: npm run docs:build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

コンフィグファイルの設定

カスタムドメインを使用しない場合、Github Pagesで公開されるドメイン以下にレポジトリ名のパスが付くので、 config.mts のbase プロパティを設定します。

// .vitepress/config.mts
import { defineConfig } from "vitepress";

export default defineConfig({
  base: "/vp-sample-blog/", // レポジトリ名を設定
  title: "My Sample Blog",
  description: "this is sample blog page.",
  ...
});

参考

• VitePress GitHub Pages

VitePressに関するその他の記事

• dark theme の色を設定する方法
• Vuetify の TreeShaking を有効化する
• Tailwind CSS のインストールと設定
• VitePress のページに React コンポーネントを表示する