Zenn
💰

Markdownでそれっぽい公式サイトを無料で公開する方法

2022/10/13に公開
Markdown
GitLab
Hugo
#
無料
tech

筆者が個人開発したHottyDBには、下記の公式サイトがあります。

https://www.hottydb.com/

↑こちらのサイトです。

Markdownを使ってこういった公式サイトを無料で構築する方法を、本記事では紹介したいと思います!!

利用したツール

それっぽさに重要なポイント

  • それっぽいHugoテーマを選ぶ
  • それっぽいロゴを作る
  • それっぽいコンテンツをMarkdownで作る

手順

1. GitLab上にProject作成

まず最初に、公式サイトのURLを決めて、GitLab上にプロジェクトを作成しましょう。

1-1. サイトのURLを決めましょう

URLを https://hogehoge.gitlab.io/docs としたい場合、

  • Gitlabのグループ名: hogehoge
  • Gitlabのプロジェクト名（サイト名）: docs

となります（次で使います）。

1-2. GitLab上にGroupとProjectを作成

GroupやProjectは非公開でも大丈夫です。
ウェブサイトのみ公開することができます。

  1. まず、GitLabのGroupを作成しましょう。
    サイトのURLが hogehoge.gitlab.io/docs にしたい場合、hogehogeに当たる部分がGroup名になります。

  2. Groupを作成したら次に、そのGroupの下に空のプロジェクト（Blank Project）を作成しましょう。
    サイトのURLが hogehoge.gitlab.io/docs にしたい場合、docsに当たる部分がProject名になります。

2. ローカル編集環境の構築

続いて、ローカル端末にHugoの編集環境を整えます。

2-0. 想定の環境

- MacOS
- Homebrewが入っている

これ以外の環境の場合はこちらを参考にHugoをインストールしてください。

2-1. Hugoをインストール

brew install hugo

2-2. サイト作成

Gitlabのプロジェクト名（サイト名）をdocsと決めた場合

hugo new site docs

作成されたサイトのディレクトリに移動して、git initをしておきましょう。

cd docs
git init

2-3. Hugoテーマを選択

（それっぽいポイント！）
それっぽい公式サイトを作成するにあたって最も重要なポイントです！

https://themes.gohugo.io/

上記テーマコレクションの中から適したテーマを選びましょう。
ただし、テーマは後からでも変更できるので、そこまで気負わず選びましょう。

ここでは、HottyDBと同じようにBookというテーマを選んだ場合の手順を記載します。

テーマの詳細ページに Download というGithubページへのリンクがあると思いますが、そのリンクをコピーしておいてください。

Bookテーマの場合、https://github.com/alex-shpak/hugo-bookがそのURLになるので、下記のようにsubmoduleとして追加します。

git submodule add https://github.com/alex-shpak/hugo-book themes/hugo-book

テーマの追加はいくつでもできますが、実際に使うテーマは設定ファイルで設定する必要があります。

config.toml をエディタで開き、以下の行を追加しましょう。

theme = "hugo-book"

また、先ほど決めたサイトのURLもconfig.tomlに設定しておきましょう。

baseURL = 'https://hogehoge.gitlab.io/docs/'

2-4. ページを追加

続いてサイトにページを追加する手順を解説します。
以下のような構成でページを作成するとします。

  • サイトTOPページ(indexページ）
  • News
    • Releases
  • Other
    • OtherのTOPページ（indexページ）
    • Terms

この場合、下記のようなコマンドでページを作成します。

hugo new _index.md
hugo new news/releases.md
hugo new other/_index.md
hugo new other/terms.md

contentsディレクトリ以下にMarkdownのファイルが作成されます。
ここで作成された .md のファイルをMarkdownで編集すれば、ページが作成されます。
ただし、ファイルのヘッダ部分に

draft: true

となっていると下書き状態となるため、 falseに変更するようにしてください。
あと、中身が何もないとファイルが認識されないので、ヘッダの下に何かしらの文字列を各ファイル記入してください。

2-5. ローカル環境での確認

hugo serverを起動します。

hugo server

そうすると、

Web Server is available at http://localhost:1313/docs/ (bind address 127.0.0.1)

のように表示されると思うので、この表示されたlocalhostのURLにアクセスして内容を確認してみましょう。

3. Gitlab Pagesによるサイトの公開

次に、一旦ここまでの内容を公開する手順を説明します。

3-1. GitLabのCI/CD設定ファイルを作成

GitLabのCI/CD設定として .gitlab-ci.yml というファイルを作成し、以下のコードをコピペしてください。
このファイルをProjectのルートディレクトリに置いておくと、MasterへPushした際に自動的にデプロイが走ります。

image: registry.gitlab.com/pages/hugo/hugo_extended:latest

variables:
  GIT_SUBMODULE_STRATEGY: recursive

pages:
  script:
  - hugo
  artifacts:
    paths:
    - public
  rules:
  - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

3-2. コードをGitLabにアップロード(push)

次に、これまで作成したHugoサイトのコードをGitLabにアップロードします。
https://gitlab.com/YourGroupName/your-hugo-site.gitの部分は、最初に作成したGitLabプロジェクトのURLになるので適宜読み替えてください

# add /public directory to our .gitignore file
echo "/public" >> .gitignore

# commit and push code to master branch
git add .
git commit -m "Initial commit"
git remote add origin https://gitlab.com/YourGroupName/your-hugo-site.git ##ここのURLは変更する！！
git push -u origin master

本家の解説も合わせて確認してください。

3-3. PJメンバー公開まで待つ

  • CI/CDの進捗状況を確認するには
    • https://gitlab.com/<YourGroupName>/<your-hugo-site>/pipelines
  • 公開されたサイトを確認するには
    • https://<YourGroupName>.gitlab.io/<your-hugo-site>/

を、確認してみてください。

この時点では、GitLabプロジェクトのメンバーだけが見える状態です。

3-4. 一般公開する

  1. https://gitlab.com/<YourGroupName>/<your-hugo-site>/editにアクセス
  2. Visibility, project features, permissionsをExpandしましょう
  3. Pagesの項目をEveryoneに変更しましょう

これで一般公開されました！　非公開にしたい場合はこちらを適宜修正しましょう。

4. それっぽいロゴを作成する

（それっぽいポイント！）
それっぽい公式サイトを作成するのに重要なポイントです！

4-1. ロゴ作成

Free Logo Makerにアクセスし、ロゴを作成し、ダウンロードしておきます。
（ユーザー登録する必要があります。画像はメールで届きます。）

4-2. ロゴを公式サイトに設置する

  1. Hugoのstatic ディレクトリに画像を配置する（画像ファイルが facebook_cover_photo_2.png だとします）
  2. content/_index.md を修正し、ヘッダのすぐ下に下記のように画像表示用のコードを挿入します
{{< figure src="facebook_cover_photo_2.png" width="100%" >}}

5. それっぽいコンテンツをMarkdownで作成する

それっぽいコンテンツを書きましょう！
文字と画像を適度に織り交ぜるのがお勧めです。

6. テーマ独自の設定など

テーマによっては独自の設定項目があったりするので、その辺りも活用しながら素敵なサイトにしてみてください！
詳しくはテーマの詳細ページなどを参照してください！

HottyDBの公式サイトでは、Bookテーマを使っており、下記の設定をconfig.tomlに追記しています。

[params]
BookSection = '*'

左枠のメニューを表示する設定です

Titleも変更して、最終的な　config.tomlは下記のようになりました。

baseURL = 'https://hogehoge.gitlab.io/docs/'

languageCode = 'en-us'
title = 'デモデス'
theme = "hugo-book"


[params]
BookSection = '*'

7. GitLabに変更をPushする

以降はGitでコミットして、プッシュするだけで自動的に公開サイトに反映されます。

この手順で作成したサイトが下記になります。

https://hogehoge6.gitlab.io/docs/

以上で手順は終了です！

ぜひ試してみてください！

Discussion