Content and layout

Writing features

Media features

Configuration path

Start with Getting started , then continue with Configuration guide and Front matter reference . The example site keeps all demo content under exampleSite/content/posts/ so each feature can be inspected as a normal Hugo post.

Hugo Linen is designed for a regular Hugo site with Hugo Extended enabled. Start with a new site or add the theme to an existing project.

hugo new site my-linen-sitecd my-linen-site

Install the theme as a Git submodule:

git submodule add https://github.com/zenpe/hugo-theme-linen themes/hugo-theme-linen

Set the theme name in your site configuration:

theme = "hugo-theme-linen"

Enable the essentials

The theme uses Hugo taxonomies for tags, categories, and series. A compact starting configuration looks like this:

[taxonomies]  tag = "tags"  category = "categories"  series = "series"[params]  photoswipe = true  lazyload = true

Add your first post

Create a post with a title, date, excerpt, and optional cover image.

---title: "Hello Linen"date: 2026-03-28T12:00:00+08:00excerpt: "A short introduction to the site."tags: [journal]---Write a concise opening paragraph, then let the typography do the rest.

Continue with Configuration guide to tune the homepage, site card, feed, and navigation.

Most visible site information lives under params. The example below configures the logo, author card, navigation, and feed path.

[params]  description = "A quiet site for notes and essays."  photoswipe = true  lazyload = true  [[params.navItems]]    name = "Archives"    path = "/archives/"  [params.logo]    src = "/linen-theme/img/logo.svg"    width = 225    height = 42  [params.info]    name = "Hugo Linen"    avatar = "/linen-theme/img/vue-color-avatar.png"    site_desc = "Readable posts, calm spacing, and useful archives."  [params.feed]    path = "/index.xml"    limit = 10

Minimal site configuration

This is a compact starting point for a new site using Hugo Linen.

baseURL = "https://example.org/"languageCode = "en"title = "My Linen Site"theme = "hugo-theme-linen"summaryLength = 36hasCJKLanguage = true[pagination]  pagerSize = 6[taxonomies]  tag = "tags"  category = "categories"  series = "series"[markup]  [markup.goldmark]    [markup.goldmark.renderer]      unsafe = true  [markup.highlight]    codeFences = true    noClasses = false[params]  description = "Notes, essays, and photo-friendly posts."  photoswipe = true  lazyload = true  [params.logo]    text = "My Linen Site"    width = 225    height = 42  [params.info]    name = "My Linen Site"    avatar = "/linen-theme/img/vue-color-avatar.png"    site_desc = "Readable posts with calm spacing."

Highlighted articles

params.topArticles controls the four highlighted cards at the top of the homepage. Entries can be page references or post slugs.

[params]  topArticles = [    "posts/getting-started",    "posts/configuration-guide",    "posts/write-with-markdown",    "posts/image-grid"  ]

The homepage skips these highlighted posts in the latest list so readers see a broader mix of content.

Lazy loading and PhotoSwipe

Images are rendered through Hugo’s image render hook. When params.lazyload is enabled, images use the theme’s placeholder and loading states. When params.photoswipe is enabled, content images can open in the PhotoSwipe lightbox.

Configure the list with page references:

[params]  topArticles = [    "posts/getting-started",    "posts/configuration-guide",    "posts/write-with-markdown",    "posts/image-grid"  ]

If an entry cannot be resolved, the theme ignores it and continues with the remaining posts. Keep the list short and intentional; the layout is optimized for four valid items.

Lists

1. Start with a direct point.
2. Keep each item focused.
3. Use paragraphs after lists when the point needs more context.

• Tags support discovery.
• Categories support broad grouping.
• Series support ordered reading.

Code

package mainimport "fmt"func main() {    fmt.Println("Hello, Hugo Linen")}

[params]  photoswipe = true  lazyload = true

Table

Footnote

Hugo renders footnotes through Goldmark.¹

Markdown image

Single landscape image

Landscape grid

Portrait grid

Mixed ratios

The shortcode supports r73, r37, r64, and r46 for two-image mixed layouts.

Unknown-size images

External or migrated image URLs may not have dimensions available during the Hugo build. The theme measures those images in the browser before PhotoSwipe opens them.

Enable RSS output in the site configuration:

[outputs]  home = ["HTML", "RSS"]  section = ["HTML", "RSS"]  taxonomy = ["HTML", "RSS"]  term = ["HTML", "RSS"]

Then configure the feed metadata:

[params.feed]  path = "/index.xml"  limit = 10  icon = "/linen-theme/favicon.svg"

The feed link in the header uses params.feed.path, so it can point to Hugo’s default /index.xml or to a custom output filename.

[params.comment]  enable = false  client_id = ""  client_secret = ""  repo = ""  owner = ""  admin = ""  pager_direction = "last"

When comments are disabled, the theme simply skips the comment container. This keeps the example site buildable without external credentials.

title: Front matter referencedate: 2026-03-28T23:52:00+08:00excerpt: A short summary for cards, feeds, and metadata.categories: Referencetags: [front-matter, reference]series: Theme Guidecover: /linen-theme/img/pattern-randomized.jpgappendRawMarkdown: truetocType: flat

excerpt controls card summaries. cover and thumbnail provide visual context. series connects posts into a series taxonomy.

Visibility controls

hide:  recent: true  archive: true

These options hide a post from the homepage latest list or archive counts while keeping the page available at its permalink.

Inline comments

This sentence contains an inline note that appears on hover.

customComments:  - text: "inline note"    comment: "This text uses the customComments front matter option."

The sample text below is intentionally plain. It tests body copy, headings, blockquotes, lists, and repeated sections without bringing in external demo content.

A measured pace

Readable pages need room to breathe, but they also need enough density for repeated use. Linen’s cards are compact on index pages, while post pages use a calmer column with clear headings and enough contrast for code and captions.

A theme should make the next sentence easy to find.

Notes

• Keep excerpts short.
• Use covers when they add context.
• Prefer a small number of meaningful tags.

Another section

The archive, taxonomy, and series views reuse the same article card language. This keeps the site predictable: a reader can move from a homepage card to an archive entry and still understand the same metadata pattern.

Longer sites benefit from this consistency. The visual system does not need many decorative states; it needs reliable spacing, stable links, and useful fallback behavior when a post has no image.