ドキュメント更新ハンズオン
ゴール
- Markdown の基本的な記法が理解できる
- VS Code Remote Continer 上の Hugo で Markdown を Web サイトコンテンツに変換できる
- GitHub Action を利用する方法がわかる
- 【Want】 Hugo の設定を変更して、Web サイトコンテンツをカスタマイズできる
目次
- VS Code Remote Container で Hugo を動かしてみよう
- Markdown でドキュメントを書いてみよう
- 自由練習1~ 好きに Markdown を書いて、Web サイトに記事を追加してみましょう
- GitHubAction で作業を自動化してみよう
- 自由練習2
- Hugo の設定を変更して、Web サイトコンテンツをカスタマイズしてみよう
VS Code Remote Container で Hugo を動かしてみよう
VS Code Remote Continer の設定がされた Git リポジトリをクローンして、さっそく Hugo がどんなものなのか体験してみましょう
(A) Windows端末
- WSL2 を起動します(Windowsキーを押下→Ubuntuを入力)
- Docker を起動しておきます:
sudo service docker start
- 任意の作業用のフォルダに移動します(例:ホームディレクトリでよければ
cd
を打てばOK) - 演習用の GitHub リポジトリを取得します(
git clone --recursive https://github.com/kazuo278/hugo-sample.git
) cd hugo-sample
でリポジトリに移動しますcode .
で VS Code を起動します(初めて実行する場合はインストールが発生します)- もし、VSCode を起動した際に信頼するかの警告が出たら「はい、作成者を信頼します」を選択します
- 右下に「Folder containes a Dev Container configuration file…」というポップアップが出たら「Reopen in Container」を選択します
- 開発用のコンテナが起動するまで待ちます(初回は時間がかかります)
- 上部メニュー>ターミナル>新しいターミナルを選択します
- 開いたターミナルで
hugo server -w
のコマンドを実行します - ブラウザで「http://localhost:1313/hugo-sample/」を開きます
- md ファイルの1つを更新して保存したときに、すぐにブラウザ側に反映されていることを確認します
(B) Mac端末
- VSCodeを起動します
shift + command + p
を押しますshell command
を入力し、「Shell Command: Install ‘code’ command in PATH」を選択します。- Docker Desktopを起動します。
- ターミナルを開き、任意の作業用のフォルダに移動します(例:ホームディレクトリでよければ
cd
を打てばOK) - 演習用の GitHub リポジトリを取得します(
git clone --recursive https://github.com/kazuo278/hugo-sample.git
) cd hugo-sample
でリポジトリに移動しますcode .
で VS Code を起動します
うまくいかない場合は、VSCodeの「File -> Open Folder」から取得したリポジトリを選択してください。- もし、VSCode を起動した際に信頼するかの警告が出たら「はい、作成者を信頼します」を選択します
- 右下に「Folder containes a Dev Container configuration file…」というポップアップが出たら「Reopen in Container」を選択します
- 開発用のコンテナが起動するまで待ちます(初回は時間がかかります)
- 上部メニュー>ターミナル>新しいターミナルを選択します(
ctrl + shift + @
でも可) - 開いたターミナルで
hugo server -w
のコマンドを実行します - ブラウザで「http://localhost:1313/hugo-sample/」を開きます
- md ファイルの1つを更新して保存したときに、すぐにブラウザ側に反映されていることを確認します
Markdwon でドキュメントを書いてみよう
Markdown記法 サンプル集 を参考にさせてもらいながら、 Markdown の記述方法を学びましょう
+α で Hugo の記事を作成する際に必要になる「メタデータ」の記載方法は以下のようになります。
---
title: "タイトル名を書きます"
date: 2022-09-08
---
ドキュメントの冒頭に"---"で囲んだ範囲に、yaml形式(ざっくりいうとパラメータと値を : で区切って表現する形式)でメタ情報を記載します!
自由練習1:好きに Markdown を書いて、Web サイトに記事を追加してみましょう
- 拡張子.mdでファイルを新規に作成します。
- 冒頭に title と date のメタデータを書いて保存します。
- ブラウザで「http://localhost:1313/hugo-sample/」を開いて記事が追加されていることを確認します
- あとは自由に Markdown で記事を書いてみてください
GitHubAction で作業を自動化してみよう
Qiita GitHub ActionsでHello Worldを参考にさせてもらいながら、GitHub Actionsを動かしてみましょう。
自由練習2:任意のブランチにPush時にソースコードを取得(checkout)するActionsを呼び、好きなLinuxコマンドを実行させてみよう
-
helloworld.yml
のon
以下を変更しますon: - workflow_dispatch - <ブランチPushイベント>
-
‘steps’以下を自由に変更します
steps: - run: echo "Hello World!" - uses: <アクション> with: <呼び出すアクションに応じて指定する> - run: <好きなlinuxコマンド>