Markdown Hugo 使い方完全ガイド：初心者が押さえるべきポイント（HugoとMarkdownの連携秘策）

初心者がHugoとMarkdownの連携をスムーズに進めるために、最初に押さえておきたいポイントを整理した完全ガイドです。これを読めば、静的サイトジェネレーターHugoの基礎から、Markdownでのコンテンツ作成、テーマ・デプロイまで一通り把握できます。

1. Hugoとは？

Hugoは「高速、柔軟、拡張性」の三拍子で動く静的サイトジェネレーター（SSG）です。

高速：Go言語で書かれているため、何万ページでも数秒でビルド。
柔軟：コンテンツはMarkdown、テンプレートはGoのtemplate言語。
拡張性：テーマやモジュールで機能拡張。

Hugoを使うと、GitHub PagesやNetlifyなどのホスティングサービスに簡単にデプロイできます。

2. Markdownの基礎

Markdownはテキストをシンプルに書いてHTMLに変換する言語。主な構文は以下。

Markdown	HTML
`# 見出し1`	`<h1>見出し1</h1>`
`## 見出し2`	`<h2>見出し2</h2>`
`イタリック`	`<em>イタリック</em>`
`ボールド`	`<strong>ボールド</strong>`
`\`“python`	`<pre><code class="language-python">`
`- リスト`	`<ul><li>リスト</li></ul>`

HugoではフロントマターというYAML、TOML、JSON形式のメタデータをMarkdown上部に書くことで、ページごとにタイトルや作成日、カテゴリを制御します。例：

---
title: "はじめてのHugo"
date: 2024-11-01
tags: ["hugo", "markdown", "static site"]
categories: ["チュートリアル"]
---

Hugoへようこそ！  
...

これでHugoは自動的に<title>や<meta>タグを生成してくれます。

3. 開発環境の構築

3.1 Hugoのインストール

OS	手順
macOS	`brew install hugo`
Windows	Chocolatey: `choco install hugo`
Linux	パッケージマネージャーまたは公式バイナリをダウンロード

3.2 プロジェクト作成

hugo new site myblog
cd myblog

これでconfig.toml（または.yaml/.json）、content/、layouts/、static/が生成されます。

3.3 GitHubリポジトリへの紐付け

git init
git remote add origin git@github.com:yourname/myblog.git
git add .
git commit -m "initial commit"
git push -u origin main

4. コンテンツの管理方法

4.1 content/ の構造

content/
│─ posts/
│  ├─ 2024-10-01-welcome.md
│  └─ 2024-10-02-tips.md
├─ categories/
│  └─ tutorial/
│       └─ setup.md
└─ tags/
    └─ hugo/
        └─ 2024-10-01-welcome.md

日付付きスラッグ（YYYY-MM-DD-title.md）は自動的にURLに反映します。
カテゴリ・タグディレクトリは任意で使えますが、検索性を高める際に有効です。

4.2 フロントマターの自動生成

hugo new posts/タイトル.md を実行すると、テンプレートに従ったフロントマターが自動作成。
カスタムフィールド（例：subtitle, summary）を追加したい場合はconfig.tomlでpaginateやarchetypesを編集します。

4.3 Markdown エディタのおすすめ

エディタ	特徴
VS Code	Live Preview,拡張機能「Markdown All in One」
Typora	WYSIWYGでサイドバーにHTMLプレビュー
Obsidian	リンク管理が強力、Markdown データベース
Notion	直感的な操作、エクスポートでMarkdown

5. テーマの選び方とカスタマイズ

5.1 テーマの取得

git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

config.toml で

theme = "ananke"

5.2 テーマのカスタマイズ

CSS/SCSS
static/css/custom.css を作り、config.toml に style = "css/custom.css" を追加。
レイアウトの編集
layouts/ 内の.htmlファイルをコピーし、変更。

ハイライト設定
config.toml

[markup]
  [markup.highlight]
    style = "monokai"
    lineNos = true

5.3 カスタムテンプレートの作成

layouts/
├─ _default/
│  ├─ baseof.html   # 全ページのベース
│  ├─ single.html   # 単一記事
│  └─ list.html     # 記事一覧
└─ partials/
   └─ header.html

baseof.html に共通ヘッダー・フッターを配置し、single.html で {{ partial "header.html" . }} など呼び出すことで共通化できます。

6. 便利なショートコードの使い方

Hugoはショートコードで記事内に埋め込み機能を実装可能。例：

{{< gallery src="image1.jpg,image2.jpg,image3.jpg" >}}

標準で埋め込めるショートコードは以下。

ショートコード	用途
`youtube`, `vimeo`	動画埋め込み
`code`	説明付きコードスニペット
`gallery`	画像ギャラリー
`embed`	外部ページ埋め込み

layouts/shortcodes/ に自前ショートコードを定義すれば、任意の機能を追加できます。

7. タクソノミー（カテゴリ・タグ）の活用

config.toml でタクソノミーを設定すると、自動的に /tags/ や /categories/ ページが生成されます。

[taxonomies]
  tag = "tags"
  category = "categories"

記事のフロントマターに tags, categories を複数指定すると、タグクラウドやカテゴリリストが便利に作れます。

8. ビルドとローカルPreview

hugo server -D

-D はDraft（下書き）記事も表示。
http://localhost:1313/ でリアルタイムプレビュー。
ファイル変更時に自動再ビルド。

9. デプロイ手順

9.1 GitHub Pages

mainブランチにプッシュ。
リポジトリ設定 → Pages → Branch: main / /docs を docs ディレクトリへ変更。
hugo ビルド後の public/ を /docs にデプロイ。

9.2 Netlify

Netlify Dashboard で「New site from Git」を選択。
ビルドコマンド: hugo
ディレクトリ: /public
自動デプロイとカスタムドメイン設定も簡単。

9.3 Vercel

Vercel 公式アプリの「Import Project」 → GitHub リポジトリ
ビルド設定: npm install && hugo && cp -r public ./out
Vercel 独自のディレクトリ構造で動作。

10. SEOとパフォーマンスの最適化

項目	実行方法
Metaタグ	`config.toml` で `metaDescription`, `author` 設定
AMP版	テーマに対応していれば `enableAMP = true`
画像最適化	`resources/` で `image
CDN	Netlify、Vercelで自動。自前の場合は CloudFront を設定
Service Worker	タイムラインで `hugo-asset` などで PWA 化

11. よくある質問とその答え

質問	回答
Hugoのバージョンが古いと動かない？	`go get -u github.com/gohugoio/hugo` で更新。
Markdownで改行が無視される	空行を入れるか `<br>` を手動挿入。
画像が表示されない	`static/img/` に入れて `![](../img/foo.png)`。ローカルは相対パスで、公開時は`/img/foo.png`。
テーマがダークモードに対応していない	`config.toml` の `colors.dark = true` を設定し、CSSに対応。
コンパイルエラー「unexpected template element」	Go template の文法ミス。`{{` と `}}` の閉じ忘れ。

12. まとめ

Hugoは高速で拡張性が高い静的サイトジェネレーター。
Markdown + フロントマターで記事を書き、Hugoが柔軟にページを生成。
テーマ・ショートコード・タクソノミーを活用すれば、デザインと機能に自由度。
ローカルPreviewで即時確認、Netlify/Vercelなら継続的デプロイが可能。
SEOとパフォーマンスを意識した構成で、検索エンジンにも友好的に。

初心者はまず「Hugoのサイトを一本作り、Markdownで数記事書いて、GitHub Pagesにデプロイ」することから始め、徐々にテーマ改造やショートコード追加を行うとよいでしょう。これで「HugoとMarkdownの連携秘策」をマスターし、安定したブログ運営が実現できます。祝実装完了！」