|
| 1 | +--- |
| 2 | +title: HugoとGitHubでObsidianで書いたメモを公開してみた |
| 3 | +created: 2025-08-20 |
| 4 | +date: 2025-08-20T22:53:23 |
| 5 | +author: shindy |
| 6 | +tags: |
| 7 | + - Hugo |
| 8 | + - GitHub |
| 9 | + - GitHub-Actions |
| 10 | + - GitHub-Pages |
| 11 | + - Obsidian |
| 12 | +draft: "false" |
| 13 | +--- |
| 14 | +## はじめに |
| 15 | +ObsidianのVault内ドキュメントの一部を[Hugo](https://gohugo.io/)という静的サイトジェネレータを用いてGitHub Pagesで公開してみました。 |
| 16 | + |
| 17 | +## 使用するもの |
| 18 | +- MacBook Air M3 |
| 19 | +- VS Code ... Hugo環境デバッグ |
| 20 | +- Obsidian ... ドキュメントの更新 |
| 21 | +- [Homebrew](https://brew.sh/ja/) ... パッケージマネージャ(Hugoインストール用) |
| 22 | +- Git ... ファイルバージョン管理(`brew install git`でインストール可能) |
| 23 | +- GitHubアカウント ... GitHubのサービスをフル活用するので必要 |
| 24 | +- (任意)Gitクライアント ... GitHub Desktop、VS Codeの拡張機能、SourceTree等使いやすいもの |
| 25 | + |
| 26 | +## ObsidianのVault構成と命題 |
| 27 | +ObsidianのVaultはGitHubのプライベートリポジトリで現在管理しています。私の場合、技術系ドキュメントと日記をひとつのVaultで管理しているので、技術系ドキュメントのみを公開する方法を模索していました。 |
| 28 | +```text |
| 29 | +├── .git/ # git |
| 30 | +├── .obsidian/ # Obsidianの設定 |
| 31 | +├── diary/ # 日記 |
| 32 | +├── docs/ # 技術系のドキュメント |
| 33 | +│ └public # 成果物 |
| 34 | +│ └draft # 下書き |
| 35 | +├── assets/ # 画像や資料アセット(docs用) |
| 36 | +├── LICENSE # リポジトリのライセンスファイル |
| 37 | +└── README.md # リポジトリのREADMEファイル |
| 38 | +``` |
| 39 | + |
| 40 | +## 今回の方針 |
| 41 | +Vault内の「docs/public」や「assets」フォルダの内容だけを公開するために、以下の手順を実施します。以降登場するリポジトリ名やブランチ名は任意です。 |
| 42 | +1. Publicリポジトリ`shindys-note`を作成する |
| 43 | + └ Hugo環境をデフォルトブランチに構築する |
| 44 | +2. GitHub Pages公開用ブランチ`gh-pages`を構築する |
| 45 | +3. Vault内対象フォルダの内容を`master`へ同期する |
| 46 | +4. `gh-pages`ブランチをGitHub Pagesで公開する |
| 47 | + |
| 48 | +## 1. Publicリポジトリ`shindys-note`を作成する |
| 49 | +### Hugoインストール |
| 50 | +[macOS](https://gohugo.io/installation/macos/) |
| 51 | +```bash |
| 52 | +brew install hugo |
| 53 | +``` |
| 54 | +### Hugo siteの作成 & 空ディレクトリ内に.gitkeepを作成 |
| 55 | +任意のディレクトリに移動してから以下コマンドを実行してください。 |
| 56 | +```bash |
| 57 | +# Hugo siteの作成 |
| 58 | +hugo new site shindys-note |
| 59 | +cd shindys-note |
| 60 | + |
| 61 | +# 空ディレクトリ内に.gitkeep(中身のないファイル)を作成(空のディレクトリはGitの追跡対象外となるため) |
| 62 | +find . -type d -empty -exec touch {}/.gitkeep \; |
| 63 | +``` |
| 64 | +### Gitの初期化 |
| 65 | +```bash |
| 66 | +# デフォルトブランチである`master`や`main`が作成される |
| 67 | +git init |
| 68 | +``` |
| 69 | +### (任意).gitignoreのおすすめ設定 |
| 70 | +.gitignoreファイルを作成しておくと、中に記述したパスをGitが自動で追跡対象外にしてくれます。 |
| 71 | +```.gitignore |
| 72 | +# Hugo build output |
| 73 | +/public/ |
| 74 | +/resources/_gen/ |
| 75 | +/hugo_stats.json |
| 76 | +/.hugo_build.lock |
| 77 | +
|
| 78 | +# Logs and OS files |
| 79 | +*.log |
| 80 | +.DS_Store |
| 81 | +Thumbs.db |
| 82 | +
|
| 83 | +# VSCode settings |
| 84 | +.vscode/ |
| 85 | +.history/ |
| 86 | +
|
| 87 | +# Node stuff (もしnpmでテーマ管理する場合は必要) |
| 88 | +node_modules/ |
| 89 | +
|
| 90 | +# Env files |
| 91 | +.env |
| 92 | +.env.* |
| 93 | +
|
| 94 | +# Backup files |
| 95 | +*~ |
| 96 | +``` |
| 97 | + |
| 98 | +### サイトの基本情報やテーマ変更やローカルでのテスト方法 |
| 99 | +GitHubへpushする前に自分の好きなテーマで記事がちゃんと表示されるかテストしましょう。 |
| 100 | + |
| 101 | +#### 基本情報(URLや言語、タイトル等) |
| 102 | +hugo.toml内で設定できます。 |
| 103 | +```toml |
| 104 | +# GitHub PagesのURLは通常、以下の形式です |
| 105 | +# https://<githubユーザ名>.github.io/リポジトリ名/ |
| 106 | +baseURL = 'https://shindy-dev.github.io/shindys-note/' |
| 107 | + |
| 108 | +languageCode = 'ja-JP' |
| 109 | +title = 'My New Hugo Site' |
| 110 | +``` |
| 111 | + |
| 112 | +#### テーマ変更 |
| 113 | +テーマは[Hugo Themes](https://themes.gohugo.io/)に一覧があります。今回は`ananke`に変更する例 |
| 114 | +```bash |
| 115 | +cd shindys-note |
| 116 | +git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke |
| 117 | +# 設定ファイルでテーマを設定すれば完了です |
| 118 | +echo 'theme = "ananke"' >> hugo.toml |
| 119 | +``` |
| 120 | + |
| 121 | +`shindys-note`を再度クローンしたときに、submoduleが配置されていない場合はリポジトリ内で以下のコマンドを実行してください。 |
| 122 | +```bash |
| 123 | +git submodule update --init --recursive |
| 124 | +``` |
| 125 | + |
| 126 | +またsubmoduleを解除(テーマをアンインストール)する場合は以下のコマンドを実行後、変更をコミットしてください。(hugo.tomlのthemeも削除してください。) |
| 127 | +```bash |
| 128 | +git submodule deinit -f themes/ananke |
| 129 | +git rm -f themes/ananke |
| 130 | +``` |
| 131 | +#### post追加 |
| 132 | +以下のコマンドで`/archetypes/default.md`をテンプレートとして`/content/posts/hello.md`を作成します。あくまでテスト用なので、自分であらかじめ作成したドキュメントを`/content/posts`へ格納してテストしていただいても構いません。テスト用のドキュメントをコミット時に対象とするかは自己判断でお願いします。 |
| 133 | +```bash |
| 134 | +hugo new posts/hello.md |
| 135 | +``` |
| 136 | +#### ローカルサーバー起動 |
| 137 | +```bash |
| 138 | +hugo server -D |
| 139 | +``` |
| 140 | +- `-D` は下書き(draft = trueの記事)も表示するオプションです。 |
| 141 | +- 起動後ブラウザで確認 → デフォルトURL:[http://localhost:1313](http://localhost:1313) |
| 142 | +- 保存するたびに自動でリロードしてくれます。 |
| 143 | + |
| 144 | + |
| 145 | +好みのテーマで作成した記事が表示されたら確認は終わりです。今回は細かなレイアウトの修正は割愛します。 |
| 146 | + |
| 147 | + |
| 148 | + |
| 149 | +### `shindys-note`をGitHub へ Publicリポジトリとして公開 |
| 150 | +GitHubのリモートリポジトリの作成方法は多種多様なので、ご自身に合うやり方で公開してください。 |
| 151 | +- Gitクライアント(GitHub Desktop等) |
| 152 | +- GitHub CLI |
| 153 | +- GitHub |
| 154 | + |
| 155 | +.gitignoreの内容にもよりますが、GitHubへは以下の構成がpushされるはずです。 |
| 156 | +```text |
| 157 | +├── .git |
| 158 | +├── archetypes |
| 159 | +├── data |
| 160 | +├── i18n |
| 161 | +├── layouts |
| 162 | +├── static |
| 163 | +├── themes |
| 164 | +├── .gitignore |
| 165 | +├── .gitmodules |
| 166 | +├── hugo.toml |
| 167 | +├── LICENSE |
| 168 | +└── README.md |
| 169 | +``` |
| 170 | + |
| 171 | +## 2. GitHub Pages公開環境を`gh-pages`ブランチに構築する |
| 172 | +ここでは、GitHub Actionsを使用して`shindys-note`のデフォルトブランチに更新があった際に、自動でHugoによるビルドを行い成果物をgh-pagesへ反映する仕組みを構築します。手順としては以下の内容を記述した`.github/workflows/deploy.yml`を`shindys-note`のデフォルトブランチで作成し、pushするだけです。コメント部分に注意して適宜修正してください。 |
| 173 | +```yml |
| 174 | +name: Deploy Hugo site to GitHub Pages |
| 175 | + |
| 176 | +on: |
| 177 | + push: |
| 178 | + branches: |
| 179 | + - master # mainの場合はここを書き換える |
| 180 | + |
| 181 | +jobs: |
| 182 | + build-deploy: |
| 183 | + runs-on: ubuntu-latest |
| 184 | + |
| 185 | + steps: |
| 186 | + - name: Checkout code |
| 187 | + uses: actions/checkout@v3 |
| 188 | + with: |
| 189 | + submodules: true # テーマをサブモジュールとして使用している場合 |
| 190 | + |
| 191 | + - name: Setup Hugo |
| 192 | + uses: peaceiris/actions-hugo@v3 |
| 193 | + with: |
| 194 | + hugo-version: '0.148.2' # 好きなHugoバージョンに変更可 |
| 195 | + extended: true # SCSS/SASSをビルドするテーマの場合はtrueにしないとエラーになる |
| 196 | + |
| 197 | + - name: Build Hugo site |
| 198 | + run: hugo --minify |
| 199 | + |
| 200 | + - name: Deploy to GitHub Pages |
| 201 | + uses: peaceiris/actions-gh-pages@v4 |
| 202 | + with: |
| 203 | + github_token: ${{ secrets.GITHUB_TOKEN }} |
| 204 | + publish_dir: ./public |
| 205 | + publish_branch: gh-pages |
| 206 | +``` |
| 207 | +
|
| 208 | +GitHubリポジトリのActionsタブを見ると成否が伺えます。 |
| 209 | + |
| 210 | +
|
| 211 | +ここまでで、`shindys-note`の環境は整いました。あとはObsidianのVault内の更新があれば`shindys-note`へ同期を行う仕組みを構築すれば、GitHub Pagesへの公開設定を実施して完了です。 |
| 212 | + |
| 213 | +## 3. Vault内対象フォルダの内容を`master`へ同期する |
| 214 | +プライベートリポジトリで管理しているObsidianのVaultの技術系ドキュメント関連ファイルに変更があった場合に、Vault内対象フォルダの「docs/public」や「assets」の内容を`shindys-note`の`master`ブランチの「content」や「assets」へ同期(置換)する仕組みを構築します。 |
| 215 | + |
| 216 | +### 3.1 Personal Access Token (PAT)の作成 |
| 217 | +リポジトリ間の操作になりますので、以下の手順でリポジトリ操作権限を持ったPATを作成します。 |
| 218 | +- GitHub から `Settings > Developer settings > Personal access tokens > Tokens (classic)` |
| 219 | +- scope: `repo` にチェックを入れる |
| 220 | +- トークンをコピーする |
| 221 | +### 3.2 PATをVaultリポジトリに設定 |
| 222 | +- Vaultリポジトリ → `Settings > Secrets and variables > Actions > New repository secret` |
| 223 | +- 名前:`NOTE_REPO_TOKEN` |
| 224 | +- 値:上でコピーしたPAT |
| 225 | + |
| 226 | +### 3.3 Vaultリポジトリ内にGitHub Actions用のスクリプトを作成 |
| 227 | +以下の内容を記述した`.github/workflows/sync-to-note.yml`を作成し、pushしてください。 |
| 228 | +pushすると、Actionsが動作し、`shindys-note`へ同期が行われます。コメント部分に注意して適宜修正してください。 |
| 229 | +```yml |
| 230 | +name: Sync Vault to shindys-note |
| 231 | +
|
| 232 | +on: |
| 233 | + push: |
| 234 | + branches: |
| 235 | + - master # Vaultのメインブランチに合わせる |
| 236 | + paths: |
| 237 | + - "docs/public/**" |
| 238 | + - "assets/**" |
| 239 | +
|
| 240 | +jobs: |
| 241 | + sync: |
| 242 | + runs-on: ubuntu-latest |
| 243 | +
|
| 244 | + steps: |
| 245 | + - name: Checkout Vault repo |
| 246 | + uses: actions/checkout@v3 |
| 247 | +
|
| 248 | + - name: Checkout shindys-note repo |
| 249 | + uses: actions/checkout@v3 |
| 250 | + with: |
| 251 | + repository: shindy-dev/shindys-note |
| 252 | + path: shindys-note |
| 253 | + token: ${{ secrets.NOTE_REPO_TOKEN }} |
| 254 | +
|
| 255 | + - name: Sync folders |
| 256 | + run: | |
| 257 | + rsync -av --delete docs/public shindys-note/content/ # テーマによってコピー先は変更してください。 |
| 258 | + rsync -av --delete assets/ shindys-note/static/assets/ # Vault の設定によって変更してください |
| 259 | +
|
| 260 | + - name: Commit and push changes |
| 261 | + run: | |
| 262 | + cd shindys-note |
| 263 | + git config user.name "github-actions[bot]" |
| 264 | + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" |
| 265 | + git add . |
| 266 | + git commit -m "Sync from Vault: $(date '+%Y-%m-%d %H:%M:%S')" || echo "No changes to commit" |
| 267 | + git push origin master # Vaultのメインブランチに合わせる |
| 268 | +``` |
| 269 | + |
| 270 | +## 4. `gh-pages`ブランチをGitHub Pagesで公開する |
| 271 | +最後に構築した公開用環境をGitHub Pagesに公開する設定を行います。 |
| 272 | +1. GitHubリポジトリのSettingsタブのPagesを選択 |
| 273 | + |
| 274 | +2. Build and deploymentのSourceに「Deploy from a branch」を選択 |
| 275 | +3. Branchには`gh-pages`、`/(root)`を設定 |
| 276 | + |
| 277 | + |
| 278 | +ローカルでテストしたときと同じ内容が表示されれば、公開完了です🎵 |
0 commit comments