Skip to content

getting-started.ja.md

Latest commit

 

History

History
311 lines (231 loc) · 8.41 KB

getting-started.ja.md

File metadata and controls

311 lines (231 loc) · 8.41 KB
Raw

スタートガイド (日本語)

このドキュメントでは、HikaeMe テーマを使って Hugo サイトを新規セットアップする手順を説明します。

前提条件

以下のツールを事前に用意してください。

  • Hugo（0.160.0 以上）
  • Go（Hugo Modules に必要）
  • Git
  • Node.js と npm
  • GCC（ネイティブ依存のビルドに必要）
  • Sass（SCSS コンパイラ）

VS Code 利用者向け（任意）として、Dev Container の実ファイル例を用意しています。

これらのファイルをプロジェクトルートの .devcontainer/ ディレクトリ（例: .devcontainer/devcontainer.json）に配置すると、VS Code から Dev Container として認識されます。 環境確認コマンド:

hugo version
go version
git --version
node --version
npm --version
gcc --version

バージョニング

HikaeMe は Go module のセマンティックインポートバージョニングに従います。

  • v1.x.x では github.com/htnabe/HikaeMe を使います
  • v2.x.x 以降では github.com/htnabe/HikaeMe/v2 を使います

v2 以降では、リポジトリ直下の go.mod に次の宣言が必要です。

module github.com/htnabe/HikaeMe/v2

セットアップ手順

Hugo サイトを新規作成

hugo new site my-blog --format yaml
cd my-blog
git init

サイトを Hugo Module として初期化

hugo mod init github.com/yourusername/my-blog

このコマンドでサイトをモジュールとして登録します。モジュール名は最終的な GitHub リポジトリ名と一致していなくても構いませんが、一意である必要があります。

HikaeMe をモジュール依存として追加

サイト設定に module import を追加します。単一ファイル構成であれば hugo.yaml を編集し、次を追加します。

module:
  imports:
    - path: "github.com/htnabe/HikaeMe/v2"

設定を分割している場合は、同じ内容を config/_default/module.yaml に配置してください。 v1.x.x を使う場合は、代わりに github.com/htnabe/HikaeMe を指定してください。

依存関係を取得

hugo mod get -u github.com/htnabe/HikaeMe/v2
hugo mod npm pack
npm install

設定ファイルの構成

設定は次のどちらでも構いません。

  • 小規模サイト向け: 単一の hugo.yaml
  • 設定が増えたサイト向け: config/_default/ で分割

このリポジトリでは設定量が多いため、config/_default/ を採用しています。典型的な構成は次のとおりです。

config/_default/
  hugo.yaml
  module.yaml
  params.yaml
  menus.yaml
  outputs.yaml
  outputFormats.yaml
  permalinks.yaml

開発サーバーを起動

hugo server -D

ブラウザで http://localhost:1313 を開いて確認します。

最小構成サンプル (hugo.yaml)

title: "My Blog"
baseURL: "https://example.com/"
locale: "ja-JP"

module:
  imports:
    - path: "github.com/htnabe/HikaeMe/v2"

params:
  author: "Your Name"
  description: "My personal blog"

このガイドでは簡潔さのため単一の hugo.yaml を使っています。設定を分割して管理したい場合は、実リポジトリの例として exampleSite/config/_default/ を参照してください。

スキルセットチャート

skill-set-chart shortcode を使うと、スキルを Bootstrap の progress bar として表示できます。データは params.author.skills に設定し、author ページなどの本文に shortcode を配置します。

params:
  author:
    skills:
      maxYears: 8
      groups:
        - name: "Programming Languages"
          items:
            - name: "TypeScript"
              years: 5
              purpose: "work and hobby"
            - name: "Python"
              years: 6.3
              purpose: "hobby"
        - name: "Libraries / Frameworks"
          items:
            - name: "Bootstrap"
              years: 4.5
              purpose: "work and hobby"
## スキルセット

{{< skill-set-chart >}}

maxYears はチャート全体の最大幅を表します。各スキルの years には整数または小数を指定でき、purpose は tooltip に表示されます。

多言語設定

HikaeMe は Hugo の多言語サイト構成に対応しています。

  • 推奨構成は、デフォルト言語をルートに置く single host 構成です
  • 既存のデフォルト言語 URL をそのまま正規 URL として維持できます
  • 追加言語は /en/ のようなプレフィックス配下で公開できます
  • UI 文言は i18n/ja.yaml、i18n/en.yaml などの翻訳ファイルで管理できます

例:

defaultContentLanguage: "ja"
defaultContentLanguageInSubdir: false

languages:
  ja:
    locale: "ja-JP"
    label: "日本語"
    weight: 1
  en:
    locale: "en-US"
    label: "English"
    weight: 2

言語ブロックに定義していない設定値はグローバル設定へフォールバックするため、差分だけを各言語に書く運用が可能です。

多言語サイトでの Algolia 検索

出力パスの仕様

Algolia JSON は home kind で生成されます。出力先は defaultContentLanguageInSubdir の値によって変わります。

defaultContentLanguageInSubdir 既定言語 他言語
false（既定値） /algolia.json /en/algolia.json
true /<defaultLang>/algolia.json /en/algolia.json

false のとき、ルートの /algolia.json が既定言語のインデックスになります。これは Hugo の仕様通りの動作であり、異常ではありません。なお、このドキュメントのサンプル設定では defaultContentLanguage: "ja" のため、true の場合の既定言語の出力先は /ja/algolia.json になります。

必要な設定

config/_default/outputFormats.yaml

Algolia:
  baseName: "algolia"
  isPlainText: true
  mediaType: "application/json"
  notAlternative: true

config/_default/outputs.yaml

home:
  - "HTML"
  - "Algolia"
section:
  - "HTML"

home だけで生成し section では生成しないことで、重複レコードを防ぎます。

config/_default/params.yaml

enableAlgolia: true

algolia:
  appId: "YOUR_APP_ID"
  searchOnlyApiKey: "YOUR_SEARCH_ONLY_API_KEY"
  indexName: "YOUR_INDEX_NAME"
  vars:
    - "title"
    - "summary"
    - "date"
    - "permalink"
  params:
    - "tags"
    - "categories"

言語別インデックス名の設定

言語ごとに別の Algolia インデックスを使う場合は、言語ブロックで indexName を上書きします。

languages:
  ja:
    params:
      algolia:
        indexName: YOUR_JA_INDEX
  en:
    params:
      algolia:
        indexName: YOUR_EN_INDEX

言語別ディレクトリでのコンテンツ管理

言語数が増える場合は、ファイル名サフィックス方式よりも言語別ディレクトリ方式 の方が管理しやすくなります。

languages の各言語に contentDir を設定します。

languages:
  ja:
    contentDir: content/ja
  en:
    contentDir: content/en
content/
  ja/
    posts/
      tech/
        article1.md
    about.md
  en/
    posts/
      tech/
        article1.md
    about.md

出力の確認方法

cd exampleSite && hugo --gc --minify

# レコード件数（どちらも 0 でないことを確認）
jq 'length' public/algolia.json
jq 'length' public/en/algolia.json

# 言語混在がないことを確認
jq '[.[].permalink | contains("/en/")] | any' public/algolia.json    # false であること
jq '[.[].permalink | contains("/en/")] | all'  public/en/algolia.json # true であること

追加ガイダンス