Skip to content

getting-started.en.md

Latest commit

 

History

History
311 lines (231 loc) · 7.22 KB

getting-started.en.md

File metadata and controls

311 lines (231 loc) · 7.22 KB
Raw

Getting Started (English)

This guide explains how to set up a new Hugo site with the HikaeMe theme.

Prerequisites

Prepare the following tools:

  • Hugo (0.160.0 or newer)
  • Go (required for Hugo modules)
  • Git
  • Node.js and npm
  • GCC (required for compiling native dependencies)
  • Sass (SCSS compiler)

For VS Code users (optional), sample dev container files are available here:

Copy these files into a .devcontainer/ directory (for example .devcontainer/devcontainer.json and .devcontainer/postCreateCommand.sh) so VS Code can detect and use them. Verify your environment:

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

Versioning

HikaeMe follows Go module semantic import versioning:

  • Use github.com/htnabe/HikaeMe for v1.x.x releases
  • Use github.com/htnabe/HikaeMe/v2 for v2.x.x and later releases

For v2 and later, the repository root go.mod must declare:

module github.com/htnabe/HikaeMe/v2

Setup Steps

Create a New Hugo Site

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

Initialize Your Site as a Hugo Module

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

This registers your site as a module. The module path does not need to match your final repository name, but it must be unique.

Add HikaeMe as a Module Dependency

Add the module import to your site configuration. For a single-file setup, edit hugo.yaml and add:

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

If you use a split configuration directory, place the same block in config/_default/module.yaml. If you are staying on v1.x.x, use github.com/htnabe/HikaeMe instead.

Download Theme Dependencies

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

Configuration Layout

You can use either of these layouts:

  • Single-file config for small sites: hugo.yaml
  • Split config for larger sites: config/_default/

This repository uses config/_default/ to keep large settings manageable. A typical split layout looks like this:

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

Start the Development Server

hugo server -D

Open http://localhost:1313 in your browser.

Minimal Configuration Example (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"

This guide uses a single hugo.yaml for brevity. If you prefer to split your configuration into multiple files, see exampleSite/config/_default/ for a working example.

Skill Set Chart

Use the skill-set-chart shortcode to show skills as Bootstrap progress bars. Configure the data under params.author.skills, then place the shortcode in a content page such as your author page.

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

{{< skill-set-chart >}}

maxYears controls the full width of the chart. Each skill's years value may be an integer or decimal value, and purpose is shown in the tooltip.

Multilingual Setup

HikaeMe supports Hugo multilingual sites.

  • Recommended setup: single host with the default language at the root
  • Existing default-language URLs can remain canonical
  • Secondary languages can live under prefixes such as /en/
  • UI strings can be managed in i18n/ja.yaml, i18n/en.yaml, and other language files

Example:

defaultContentLanguage: "ja"
defaultContentLanguageInSubdir: false

languages:
  ja:
    locale: "ja-JP"
    label: "Japanese"
    weight: 1
  en:
    locale: "en-US"
    label: "English"
    weight: 2

Hugo will fall back to global configuration values for keys not defined inside a language block, which makes it practical to localize only the settings that differ.

Algolia Search with Multilingual Sites

Output path behavior

Algolia JSON is generated at the home kind. Its output path depends on defaultContentLanguageInSubdir:

defaultContentLanguageInSubdir Default language Other languages
false (default) /algolia.json /en/algolia.json
true /<defaultLang>/algolia.json /en/algolia.json

With false, the root /algolia.json is the default-language index. This is expected Hugo behavior, not a bug. In this documentation's sample config, defaultContentLanguage: "ja", so with true the default-language output path becomes /ja/algolia.json.

Required config

config/_default/outputFormats.yaml

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

config/_default/outputs.yaml

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

Generate only at home, not section, to avoid duplicate records.

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"

Per-language index names

To use separate Algolia indexes per language, override indexName in the language block:

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

Content organization by language

When using many languages, organizing content by language directory is easier to maintain than filename suffixes.

Add contentDir for each language in languages config:

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

Verifying the output

cd exampleSite && hugo --gc --minify

# record counts (both should be non-zero)
jq 'length' public/algolia.json
jq 'length' public/en/algolia.json

# confirm no cross-language contamination
jq '[.[].permalink | contains("/en/")] | any' public/algolia.json   # expect false
jq '[.[].permalink | contains("/en/")] | all'  public/en/algolia.json  # expect true

Additional Guidance