LoginSignup
15
7
Ateam Finergy Inc.Advent Calendar 2020Day 2finergy-a-tm
@s3710(ミナト)

HUGOでシンプルなドキュメントサイトをつくる

Last updated at Posted at 2020-12-01

エイチームフィナジーの@Minashoです。
本記事は、Ateam Finergy Inc. Advent Calendar 2020の2日目に公開された記事です。

はじめに

静的サイトジェネレーターHUGOを使って、ドキュメントサイト(wiki)を制作します。

はてなブログやWordPress等のCMS(Contens Management System)でもドキュメントサイトを作ることは可能です。
しかし、ブログ用CMSだとデザインの制約が大きいという問題があり、WordPressはサーバーとドメインを用意する必要があり、コストが発生します。

静的サイトジェネレーターであるHUGOは、学習コストはありますが、無料で利用できます。
GitHub Pages等のホスティングサービスで無料公開も可能です。

今回使用するテーマのデモサイト

静的サイトとは

まず、静的サイトとは、ユーザーのアクセスに対して用意してあるHTMLを返すだけのサイトです。
いつ誰が閲覧しても、同じページが表示されます。
したがって、ユーザーによって内容が変わらないwikiやブログ、コーポレートサイトが適しています。

私が所属しているエイチームフィナジーのコーポレートサイトも静的サイトです。

一方、掲示板やSNSなど、見るタイミングやユーザーによって表示内容が変わるサイトは動的サイトで実現できます。
サーバーにリクエストがあった時に、DB内のデータやテンプレートからHTMLファイルを生成し、ユーザーに返します。

静的サイトのメリットは、表示速度が早いこと。
デメリットは、1ページごとにHTMLファイルを用意する必要があり、手間がかかること。

このデメリットを解消してくれるのが、静的サイトジェネレーターになります。

静的サイトジェネレーターとは

名前の通り、静的サイトを生成してくれるツールです。

コンテンツを書いてビルドを実行すれば、ヘッダーやフッター、サイドバーなどを含んだHTMLファイルを自動で生成してくれます。

ブログサービス同様、コンテンツを書くことに集中できるというわけです。

HUGOとは

HUGOは静的サイトジェネレーターのひとつです。
GO言語で作られており、他の静的サイトジェネレーターよりもビルドが高速であるという特徴があります。

また、デザインテンプレートが豊富な印象です。

10分でサンプルサイトを制作する

それでは、HUGOを使って実際にドキュメントサイトを作っていきましょう！

HUGOをインストール

Homebrewをインストールしていない方は事前にインストールしておきます。

Terminal
# Homebrewインストール
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

次はHUGOをインストールします。

Terminal
# HUGOをインストール
$ brew install hugo
# バージョンを確認
$ hugo version

サイトを作成する

Terminal
$ hugo new site sample_document
# 以下の構成でsample_documentディレクトリが生成されます
sample_document
├── archetypes
│   └── default.md
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

テーマを適応する

今回はtechdocというドキュメントのHUGO公式テーマを使用します。
HUGOの公式テーマはGitHubで管理されているので、アップデートに対応するためサブモジュールでcloneします。

Terminal
# gitインストール
$ brew install git
Terminal
# sample_document配下に移動
$ cd sample_document
$ git init
# themesにテーマをclone
$ git submodule add https://github.com/thingsym/hugo-theme-techdoc.git themes/hugo-theme-techdoc

続いて、HUGOの設定ファイルであるconfig.tomlを編集します。
テーマをcloneしたらthemes/hugo-theme-techdoc/exampleSite/にサンプルの記事や設定ファイルが置いてあるので、そちらを利用します。

サンプル用に編集した以下のコードをconfig.tomlにコピペしましょう。

今回使用しない変数や設定は#でコメントアウトしています。
(様々な機能が用意されているので慣れてきたら読んでみましょう)

config.toml
baseURL = "https://example.com"

languageCode = "jp"
DefaultContentLanguage = "jp"
title = "サンプルドキュメント"
theme = "hugo-theme-techdoc"

hasCJKLanguage = true
metaDataFormat = "yaml"

defaultContentLanguage = "jp"
defaultContentLanguageInSubdir= false
enableMissingTranslationPlaceholders = false

[params]

    # Source Code repository section
    description = "これはサンプルドキュメントです"
    # github_repository = "https://github.com/thingsym/hugo-theme-techdoc"
    # version = "0.9.6"

    # Documentation repository section
    # documentation repository (set edit link to documentation repository)
    github_doc_repository = "https://github.com/thingsym/hugo-theme-techdoc"

    # Analytic section
    google_analytics_id = "" # Your Google Analytics tracking id
    tag_manager_container_id = "" # Your Google Tag Manager container id
    google_site_verification = "" # Your Google Site Verification for Search Console

    # Open Graph and Twitter Cards settings section
    # Open Graph settings for each page are set on the front matter.
    # See https://gohugo.io/templates/internal/#open-graph
    # See https://gohugo.io/templates/internal/#twitter-cards
    title = "Hugo Techdoc Theme"
    images = ["images/og-image.png"] # Open graph images are placed in `static/images`

    # Theme settings section
    # Theme color
    # See color value reference https://developer.mozilla.org/en-US/docs/Web/CSS/color
    custom_font_color = ""
    custom_background_color = ""

    # Documentation Menu section
    # Menu style settings
    menu_style = "open-menu" # "open-menu" or "slide-menu" or "" blank is as no sidebar

    # Date format
    dateformat = "" # default "2 Jan 2006"
    # See the format reference https://gohugo.io/functions/format/#hugo-date-and-time-templating-reference

    # path name excluded from documentation menu
    menu_exclusion = [
        "archives",
        "archive",
        "blog",
        "entry",
        "post",
        "posts",
    ]

    # Algolia site search section
    # See https://www.algolia.com/doc/
    algolia_search_enable = true
    algolia_indexName = "hugo-demo-techdoc"
    algolia_appId = "7W4SAN4PLK"
    algolia_apiKey = "cbf12a63ff72d9c5dc0c10c195cf9128" # Search-Only API Key

# Global menu section
# See https://gohugo.io/content-management/menus/
# [menu]
#   [[menu.main]]
#       name = "Home"
#       url = "/"
#       weight = 1
#
#   [[menu.main]]
#       name = "Twitter"
#       url = "https://twitter.com/thingsym"
#       weight = 2

# Markup configure section
# See https://gohugo.io/getting-started/configuration-markup/
[markup]
    defaultMarkdownHandler = "goldmark"
    [markup.goldmark.renderer]
        unsafe= true
    [markup.tableOfContents]
        startLevel = 2
        endLevel = 6
        ordered = false

[outputs]
    home = ["HTML", "RSS", "Algolia"]

# Algolia Search configure section
[outputFormats.Algolia]
    baseName = "algolia"
    mediaType = "application/json"
    isPlainText = true
    notAlternative = true

[params.algolia]
    vars = [
        "title",
        "summary",
        "content",
        "date",
        "publishdate",
        "description",
        "permalink",
        "keywords",
        "lastmod",
    ]
    params = [
        "tags",
        "categories",
    ]

テーマを適応してHUGOを起動してみます。

Terminal
$ hugo server -D

起動したら下記URLにアクセスしてみましょう！
http://localhost:1313/
スクリーンショット 2020-11-29 19.54.01.png

Ctrl+Cで一旦サーバーをストップさせましょう。

コンテンツを追加する

コンテンツを追加していきましょう。
コンテンツはcontent配下に設置します。

ファイル冒頭の---で囲まれた部分は、Front Matterと呼ばれます。
様々な変数を扱えるのですが、ここではタイトル・日付・公開or非公開を扱います。

content
├── _index.md     # トップページ
└── chapter1      # 親要素
    ├── _index.md # /chapter1で表示
    └── 1.md      # /chapter1/1で表示
_index.md
---
title: "Chapter 1"
date: 2020-11-29
draft: false # 非公開ならtrueにする
---

ここに内容を書く。
1.md
---
title: "Chapter 1-1"
date: 2020-11-29
draft: false
---

ここに内容を書く。

再びサーバーを起動してサイトを確認してみましょう。

Terminal
$ hugo server -D

スクリーンショット 2020-11-29 21.04.18.png

サイドバーにメニューが表示されました！

デザインを編集したい

サイトのデザインはsample_document/themes/hugo-theme-techdoc/layoutsで管理されています。
編集したい時は、sample_document/layouts以下に同じファイルをコピーして編集します。

すると、上位側のデザインが優先されて表示されます。
テーマのアップデートに備えて、themes配下のファイルは直接編集しないようにしましょう。

ホスティングサービスで公開する

GitHub Pages等で公開する場合、ビルド(HTMLファイルを生成する作業)が必要になります。
NetlifyはHUGOがインストールされており、連携したリポジトリにpushするだけでビルドもしてくれます。

ホスティングの方法に関しては、今回省略します。

Terminal
# ビルドコマンドを実行
$ hugo
# public配下に全てのHTMLファイルが生成される
sample_document
└── public
    ├── 404.html
    ├── algolia.json
    ├── categories
    │   ├── index.html
    │   └── index.xml
    ├── chapter1
    │   ├── 1
    │   │   └── index.html
    │   ├── index.html
    │   └── index.xml
    ├── css
    │   ├── chroma.css
    │   ├── chroma.min.css
    │   ├── theme.css
    │   └── theme.min.css
    ├── index.html
    ├── index.xml
    ├── js
    │   └── bundle.js
    ├── sitemap.xml
    └── tags
        ├── index.html
        └── index.xml

おわりに

HUGOは公式テーマが豊富なので、初心者でも扱いやすい静的サイトジェネレーターだと思います！
ただ、設定ファイルの使い方などは、テーマによって大きく異なるので最初は苦戦するかもしれません。

テーマによっては、導入方法や使い方などが丁寧に説明してあるので安心です。
今回使用したテーマのデモサイト↓
https://themes.gohugo.io//theme/hugo-theme-techdoc/

参考

HUGO公式ドキュメント
https://gohugo.io/documentation/
Quick Start
https://gohugo.io/getting-started/quick-start/

15
7
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
15
7