hugo-primer-blog — Hugo Blog Template

SHA-256: 8965a6c383e2e7dc60f5c69ef3b7d2995d4469929502682cb5d338bbf43f0ccd

2026-10-02T10:23:31.144Z

# Primer Blog

![screenshot](https://raw.githubusercontent.com/ngs/hugo-primer-blog/main/images/screenshot.png)

A clean, responsive Hugo blog theme using GitHub's [Primer CSS](https://primer.style/) design system.

**[Live Demo](https://hugo-primer-blog-demo.ngs.io)**

## Features

- **Dark Mode** - Automatic system preference detection with manual override, saved to localStorage
- **Multilingual** - Full i18n support with included English and Japanese translations
- **Responsive Design** - Looks great on all devices with optional sidebar layout
- **Primer CSS** - Built on GitHub's design system for a clean, modern look
- **Customizable Primary Color** - Easy accent color customization via config
- **Markdown Styling** - Full Primer markdown styling for rich content
- **LLM-friendly Output** - Optional `llms.txt` site index and per-page raw Markdown for AI consumption
- **Hugo Pipes** - Built with Hugo Pipes for optimized asset handling

## Requirements

- Hugo v0.146.0 or later (Extended version not required)
- Node.js and npm (for Primer CSS dependencies during theme development)

## Installation

### As a Hugo Module (Recommended)

1. Initialize your Hugo site as a module:

```bash
hugo mod init github.com/your-username/your-site
```

2. Add the theme to your `hugo.toml`:

```toml
[module]
  [[module.imports]]
    path = "go.ngs.io/hugo-primer-blog"
```

> **Note:** This theme uses a vanity import path. The module is hosted at [go.ngs.io/hugo-primer-blog](https://go.ngs.io/hugo-primer-blog/) and resolves to the GitHub repository.

### As a Git Submodule

1. Add the theme as a submodule:

```bash
git submodule add https://github.com/ngs/hugo-primer-blog.git themes/hugo-primer-blog
```

2. Install npm dependencies:

```bash
cd themes/hugo-primer-blog
npm install
```

3. Set the theme in your `hugo.toml`:

```toml
theme = "hugo-primer-blog"
```

## Configuration

### Basic Configuration

```toml
baseURL = "https://example.com/"
title = "My Blog"
theme = "hugo-primer-blog"

defaultContentLanguage = "en"
defaultContentLanguageInSubdir = true

[params]
  sidebar = true            # Enable/disable sidebar
  recentPostsCount = 5      # Number of recent posts in sidebar module
  defaultTheme = "auto"     # auto, light, or dark
  dateFormat = "2006-01-02"
  showReadingTime = true
  showAuthor = true
  showShareButtons = true
  googleAnalyticsID = "G-XXXXXXXXXX"  # Google Analytics 4 ID

  # Sidebar modules - order determines display order
  # Available: recentPosts, tags, categories, archive, links (+ custom partials)
  [[params.sidebarModules]]
    partial = "recentPosts"

  [[params.sidebarModules]]
    partial = "tags"

  [[params.sidebarModules]]
    partial = "archive"

  [params.social]
    github = "your-username"
    x = "your-username"

  # Custom favicon (optional)
  faviconIco = "favicon.ico"
  faviconPng = "favicon.png"

  # Apple Touch Icons (optional)
  [[params.appleTouchIcons]]
    sizes = "180x180"
    href = "apple-touch-icon-180x180.png"
  [[params.appleTouchIcons]]
    sizes = "152x152"
    href = "apple-touch-icon-152x152.png"
```

### Multilingual Configuration

```toml
[languages]
  [languages.en]
    languageName = "English"
    weight = 1
    contentDir = "content/en"

  [languages.ja]
    languageName = "日本語"
    weight = 2
    contentDir = "content/ja"
```

### Menus

```toml
[menus]
  [[menus.main]]
    name = "Home"
    url = "/"
    weight = 1

  [[menus.main]]
    name = "Posts"
    url = "/posts/"
    weight = 2

  [[menus.footer]]
    name = "Privacy"
    url = "/privacy/"
    weight = 1
```

## Content Structure

```
content/
├── en/
│   ├── posts/
│   │   └── my-post.md
│   └── about.md
└── ja/
    ├── posts/
    │   └── my-post.md
    └── about.md
```

### Front Matter

```yaml
---
title: "My Post Title"
date: 2024-01-15
draft: false
tags: ["hugo", "primer"]
categories: ["tutorial"]
author: "Your Name"
description: "A brief description of the post"
image: "/images/featured.jpg"  # Optional featured image (992×525 recommended; rendered at that aspect ratio)
hideReadingTime: true          # Optional: hide reading time for this page
---
```

### Custom Open Graph (OGP) Meta Tags

You can customize Open Graph meta tags per page using the `ogp` frontmatter. The structure is recursively converted to meta tags:

```yaml
---
title: "About Me"
ogp:
  og:
    type: profile
  profile:
    first_name: Atsushi
    last_name: Nagase
    username: ngs
    gender: male
---
```

This generates:

```html
<meta property="og:type" content="profile">
<meta property="profile:first_name" content="Atsushi">
<meta property="profile:last_name" content="Nagase">
<meta property="profile:username" content="ngs">
<meta property="profile:gender" content="male">
```

Nested structures are supported with colon-separated property names:

```yaml
ogp:
  foo:
    bar:
      baz: "value"
```

Outputs: `<meta property="foo:bar:baz" content="value">`

Arrays generate multiple meta tags with the same property:

```yaml
ogp:
  article:
    tag:
      - Hugo
      - Blog
      - Tech
```

Outputs:

```html
<meta property="article:tag" content="Hugo">
<meta property="article:tag" content="Blog">
<meta property="article:tag" content="Tech">
```

Default `og:*` tags (title, description, type, url, image, site_name, locale) are automatically generated unless overridden in the `ogp.og` section.

## LLM-friendly Output (llms.txt & Markdown)

The theme ships two optional [output formats](https://gohugo.io/configuration/output-formats/) that make your content easy for LLMs and AI agents to consume:

- **`LLMS`** - renders a single `/llms.txt` on the home page: an index of your posts (title, link, and description) following the [llms.txt](https://llmstxt.org/) convention.
- **`Markdown`** - renders a raw Markdown `index.md` next to each page's `index.html`, containing the page's original Markdown content without HTML rendering.

### Enabling

The theme **defines** these output formats (and their media types) and provides the templates, but does not enable them by default. You opt in per site via `[outputs]`:

```toml
[outputs]
  home = ["HTML", "RSS", "LLMS"]
  page = ["HTML", "Markdown"]
```

> **Why opt in here, and not in the theme?** Hugo merges most config keys from themes, but the `outputs` key uses the `none` merge strategy, so it is **not** inherited from a theme. The format *definitions* (`outputFormats` / `mediaTypes`) use the `shallow` strategy and *are* inherited, so all you need in your own config is the `[outputs]` block above. See [Merge configuration from themes](https://gohugo.io/configuration/introduction/#merge-configuration-from-themes).

Once enabled, `hugo` generates:

```
public/
├── llms.txt                       # site index (home page)
├── about/
│   └── index.md                   # raw Markdown for the About page
└── posts/
    └── my-post/
        ├── index.html
        └── index.md               # raw Markdown for the post
```

For multilingual sites, one `llms.txt` is generated per language (e.g. `/llms.txt` and `/ja/llms.txt`), automatically using each language's title, description, and posts.

### Customizing

The output is rendered by two templates you can override like any other:

- `layouts/home.llms.txt` - the `llms.txt` index. By default it lists pages in the `posts` section.
- `layouts/page.md` - the per-page Markdown rendering.

Copy either file into your site's `layouts/` directory to customize it.

## Customization

### Primary Color

You can customize the accent color used for links, tags, pagination, and other interactive elements:

```toml
[params]
  primaryColor = "#8250df"  # Purple
```

This overrides the default GitHub blue (`#0969da`) with your chosen color. The theme automatically generates appropriate shades for light and dark modes.

### Custom CSS

Create `assets/css/custom.css` in your site root to add custom styles:

```css
/* Your custom styles here */
```

The theme's own styles live in `assets/css/primer-blog.css`. Your `custom.css` is loaded *after* it, so your rules override the theme without shadowing it. (See `exampleSite/assets/css/custom.css` for a working example.)

### Overriding Templates

Copy any template from the theme's `layouts/` directory to your site's `layouts/` directory to override it.

## Development

To run the example site:

```bash
git clone https://github.com/ngs/hugo-primer-blog.git
cd hugo-primer-blog
npm install
hugo server --source exampleSite
```

Then open http://localhost:1313 in your browser.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This theme is released under the [MIT License](LICENSE).

## Credits

- [Hugo](https://gohugo.io/) - The world's fastest static site generator
- [Primer CSS](https://primer.style/) - GitHub's design system