Hugoでサイト作りたい

昔，身内向けに作ったHugoでサイト作ってGitHub Pagesで公開する手順を説明するための資料

Transcript

1. Hugoでサイト作って公開したい eqs ( https://github.com/eqs ) 1/28
2. この資料について ⾝内向けに作った，HugoでWebサイト作ってGitHub Pagesで公開す るまでの⼿順を説明するためのもの資料を公開⽤に少し修正したもの Gitをフル活⽤するので，先に下記資料でバージョン管理システムと Gitについて解説した上で本資料を使った 数値計算屋のためのGit⼊⾨ / Starting Git https://speakerdeck.com/kaityo256/starting-git GitHub Actionsでデプロイの⾃動化までやってるけどスライドにする のが⼤変だったのでその辺はコード⾒せながら説明する感じ 2/28
3. Hugoのサイトを作る 3/28
4. Hugoのプロジェクトを作る mysite という名前でHugoのプロジェクトを作るコマンド︓ $ hugo new site mysite 出⼒︓ Congratulations! Your new Hugo site is created in C:\Users\<user>\workspace\webpage\mysite. Just a few more steps and you're ready to go: 1. Download a theme into the same-named folder. Choose a theme from https://themes.gohugo.io/ or create your own with the "hugo new theme <THEMENAME>" command. 2. Perhaps you want to add some content. You can add single files with "hugo new <SECTIONNAME>\<FILENAME>.<FORMAT>". 3. Start the built-in live server via "hugo server". Visit https://gohugo.io/ for quickstart guide and full documentation. 4/28
5. Gitのリポジトリとして初期化する 予めGitにユーザ名とメールアドレスを設定しておく $ git config --global user.name "Your GitHub Username" $ git config --global user.email "Your GitHub E-mail address" $ git config --list # 設定内容の確認 さっき作った mysite の中に移動して初期化 $ cd mysite $ git init 余計なファイルを消して最初のコミットをする $ del archetypes\default.md $ git status $ git add . $ git commit -m "initial commit." 5/28
6. .gitignore の追加 .gitignore はGitの管理下におきたくないファイルを指定するためのフ ァイル gitignore.ioからHugo⽤の .gitignore を取得する https://www.toptal.com/developers/gitignore $ code .gitignore # .gitignoreを作って編集する $ git status $ git add . $ git status $ git commit -m "Add gitignore" 6/28
7. テーマを追加する テーマをGitのsubmoduleとして追加する（ git submodule ） 解説記事によっては，submoduleを使ってないことがある submoduleにしておく⽅がテーマのバージョンが変わったときの 更新が楽 $ cd themes $ git submodule add https://github.com/kakawait/hugo-tranquilpeak-theme.git $ git status # 既にaddされた状態になってるのがわかる $ git commit -m "Add theme" 7/28
8. config.toml を書き換える テーマのサンプルに付属してるやつを元に書き換えればok themes/hugo-tranquilpeak-theme/exampleSite/config.toml 8/28
9. サイトのビルドとプレビュー サーバを⽴ち上げるコマンド $ hugo server http://localhost:1313 にブラウザからアクセスするとサイトのプレビ ューが⾒られる まだ何もページ作ってないのでメニュー以外なんもない サーバを⽌めるときはCtrl+C 9/28
10. CVのページを作る 次のコマンドでページを新しく作る $ hugo new page/cv.md テーマ hugo-tranquilpeak-theme では，ブログ記事以外のページを作る 際， page というフォルダの中にmdファイルを⼊れないといけない hugo server を実⾏してから http://localhost:1313/page/cv にアクセス するとさっき作ったCVが⾒られる サーバを⽴ち上げたまま page/cv.md を編集するとすぐに内容が反映さ れる 10/28
11. GitHubを使う 11/28
12. Hugoのプロジェクトを管理するためのリ モートリポジトリを作る GitHubの右上のメニューの "New repository"にアクセス ここでは， mysite-hugo という名前にしておく（なんでもいい） 12/28
13. ローカルリポジトリをリモートリポジト リにPushする Pushを⾔い換えると，ローカルリポジトリの履歴データベースをリモ ートリポジトリのデータベースにコピーする操作 # Pushする先を設定しておく $ git remote add origin https://github.com/eqs/mysite-hugo.git # ローカルのmasterブランチをoriginにPush $ git push origin master .git .git ローカルリポジトリ リモートリポジトリ Push 13/28
14. Tranquilpeakをカスタマイズする 14/28
15. トップページのカスタマイズ トップページに page/cv.md を表⽰するためにテーマをカスタマイズす る 以下の内容を layouts/index.html にコピペするとテンプレート内の対 応するファイルの代わりにこちらが使われる テーマの中⾝をいじらなくても同名のファイルを⾃分のプロジェク トに置く最⼩限の作業だけでカスタマイズができるのが便利 {{ with .Site.GetPage "page/cv" }} {{ .Render }} {{ end }} 15/28
16. その他のカスタマイズ メニューの余計な項⽬削りたい config.toml をいじる 16/28
17. GitHub Pagesでサイトを公開する 17/28
18. GitHub Pagesによるサイト公開の仕組み Webサイトやサービスを公開して誰かが⾒たり使えるようにすること をデプロイとよぶらしい <ユーザ名>.github.io という名前のリポジトリにWebページを置く https://<ユーザ名>.github.io として公開される 個⼈や組織のページ作るのによく使われる あるリポジトリの gh-pages という名前のブランチにWebページを置く https://<ユーザ名>.github.io/<リポジトリ名> として公開される ソフトウェアのドキュメントやプロジェクトページを公開するのに 使われる 例︓ https://eqs.github.io/ https://eqs.github.io/Here_are_Dice/ 18/28
19. (追記) GitHub Pagesによるサイト公開の 仕組み サイトの公開設定があるページ: https://github.com/<username>/<repository>/settings/pages ここで設定したブランチがGitHub Pagesとして公開される 元のリポジトリがプライベートでもサイトは公開されるので注意 逆に，Hugoのコードは master ブランチに，公開⽤コードは gh-pages ブランチに置いておくことで，単体のリポジトリでサイ トの運⽤ができる 19/28
20. サイトをGitHub Pagesで公開したい まず，Hugoのプロジェクトをビルドしてみよう $ hugo public というフォルダの中にサイトのファイルが⽣成されてるはず （このフォルダは .gitignore に⼊ってるのでGitから無視される） public の中⾝をリモートリポジトリ <ユーザ名>.github.io にpushすると 公開される .git ローカル リポジトリ リモート リポジトリ (mysite-hugo) Push リモート リポジトリ (<username>.github.io) .git Push .git config.toml content hugoコマンド によるビルド public 20/28
21. GitHub ActionsによるHugo製Web サイトの⾃動デプロイ 21/28
22. 参考 https://qiita.com/peaceiris/items/d401f2e5724fdcb0759d https://github.com/marketplace/actions/github-action-to-push- subdirectories-to-another-repo 22/28
23. ⾃動デプロイの流れ サイト編集⽤のリポジトリ（mysite-hugo）と公開⽤リポジトリ （<username>.github.io）があるのでこんな構成になってる .git ローカル リポジトリ リモート リポジトリ (mysite-hugo) Push クラウド上の 仮想環境 Clone .git config.toml content hugoコマンド によるビルド public リモート リポジトリ (<username>.github.io) .git Push .git config.toml content 23/28
24. やること ワークフロー ( .github/workflows/build.yaml ) を作る ファイル名はなんでもいいけど場所だけ注意 API_TOKEN を作る ⾃分のリポジトリにアクセスするために必要なキー 24/28
25. ワークフロー name: github pages on: push: branches: master jobs: deploy: name: Build Hugo Site runs-on: ubuntu-18.04 steps: - name: Install Hugo env: HUGO_VERSION: 0.74.1 run: | mkdir ~/hugo cd ~/hugo curl -L "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_Linux-64bit.tar.gz" --output hugo.tar.gz tar -xvzf hugo.tar.gz sudo mv hugo /usr/local/bin - name: Checkout master branch uses: actions/checkout@v2 with: ref: master path: main submodules: true - name: Checkout eqs.github.io uses: actions/checkout@v2 with: repository: eqs/eqs.github.io ref: master path: gh-pages submodules: true - name: Hugo Build run: cd main && hugo - name: Copy files run: cp -rf main/public/* gh-pages/ - name: Commit changes run: | cd gh-pages git config --local user.email "actions@github.com" git config --local user.name "GitHub Action" git add -A . if git diff-index --quiet HEAD --; then echo "No changes..." else msg="Rebuilding site `date`" if [ $# -eq 1 ] then msg="$1" fi git commit -m "[CI] build hugo static site $msg" fi - name: Push to the repository uses: cpina/github-action-push-to-another-repository@v1.1 env: API_TOKEN_GITHUB: ${{ secrets.API_TOKEN_GITHUB }} with: source-directory: 'gh-pages' destination-github-username: 'eqs' destination-repository-name: 'eqs.github.io' 25/28
26. 付録︓Git Tips 26/28
27. Win10で git log とかの⽇本語が⽂字化け する現象の解消 Gitの中で使われる⽂字コードを指定することで回避できるっぽい $ git config --global core.pager "LESSCHARSET=utf-8 less" https://qiita.com/Fushihara/items/c21172e707d57c833e7e 27/28
28. 連絡フォームの設置 こういうやつ︓ https://www.eqseqs.work/contact/ ⾃分からメールアドレスを晒さずに相⼿からコンタクトもらえるの で便利 ⾃分はFormspree ( https://formspree.io/ ) を使ってる 28/28