Linewise

Welcome to Linewise

Wed, 10 Jun 2026 00:00:00 +0000

Linewise is a Hugo theme for personal blogs built around Vim’s interaction model. Posts are buffers, search borrows from quickfix, and the interface uses Vim as an information architecture without sacrificing reading comfort.

The goal is not to cosplay a terminal. The goal is to keep the directness of Vim: dense enough to scan, calm enough to read, and predictable enough to live with for years.

What you get

Linewise ships as a theme engine. Keep your posts, config, and branding in your site, and update the theme separately.

Getting Started with Linewise

Tue, 09 Jun 2026 00:00:00 +0000

Linewise is a Hugo theme. Your site owns the content, config, and branding; the theme owns the layouts, styles, and interaction model.

Installation

Create a Hugo site:

hugo new site my-blog
cd my-blog

Then choose one installation mode.

Git submodule

Add Linewise under themes/linewise:

git submodule add https://github.com/tabsp/linewise themes/linewise

Configure Hugo with theme = "linewise":

baseURL = "https://example.com"
title = "My Blog"
locale = "en"
theme = "linewise"

Hugo Module

Initialize module support in your site:

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

Import Linewise in hugo.toml:

Buffers, Not Tabs

Mon, 08 Jun 2026 00:00:00 +0000

Most blog themes think in pages. Linewise thinks in buffers.

That small shift changes the interface. A homepage becomes :ls, a posts list becomes :oldfiles, tags become marks, and search behaves like :find feeding a quickfix list.

Spatial model

The browser viewport is treated as an editor frame. Each region has a Vim name and a specific job:

Region	Role
`command-bar`	The command-line area and top-level navigation
`file-explorer`	A compact tree exposing the blog’s content structure
`bufferline`	The visible set of open/recent buffers
`workspace`	The active window inside the main editor column
`status-line`	Mode, current buffer, context, and progress

The default desktop layout arranges these like a windowed editor:

Theme Reference

Sun, 07 Jun 2026 00:00:00 +0000

This reference is the canonical user-facing documentation for Linewise.

Requirements

Hugo Extended 0.146.0 or newer
Git, when installing with a submodule
Go, when installing with Hugo Modules

Installation

Choose one installation mode per site. Do not configure both a git submodule and a Hugo Module import in the same site.

Git submodule

hugo new site my-blog
cd my-blog
git submodule add https://github.com/tabsp/linewise themes/linewise

baseURL = "https://example.com"
title = "My Blog"
locale = "en"
theme = "linewise"

Hugo Module

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

baseURL = "https://example.com"
title = "My Blog"
locale = "en"

[module]
[[module.imports]]
path = "github.com/tabsp/linewise"

Required site config

[taxonomies]
tag = "tags"

[params.linewise]
description = "Notes from the command line."
author = "Your Name"
locale = "en"
favicon = "favicon.svg"
ogImage = "og.svg"
showExplorer = true
showBufferline = true

[params.linewise.comments]
provider = "none"

[outputs]
home = ["HTML", "RSS", "JSON"]

[outputFormats.JSON]
mediaType = "application/json"
baseName = "search"
isPlainText = true

[markup.highlight]
noClasses = false

Linewise ships CSS for Hugo’s class-based Chroma output. Keep noClasses = false so code blocks use the theme palette.

Customizing Linewise

Sat, 06 Jun 2026 00:00:00 +0000

Linewise is designed to keep routine customization in Hugo config and site-owned assets. Override templates only when configuration is not enough.

Public config

Theme-owned options live under [params.linewise].

[params.linewise]
description = "A personal blog."
author = "Your Name"
locale = "en"
favicon = "favicon.svg"
ogImage = "og.svg"
showExplorer = true
showBufferline = true

Key	Default	Purpose
`description`	site description fallback	SEO and Open Graph fallback text
`author`	empty	Author metadata where templates need it
`locale`	site locale	Theme-owned locale fallback for widgets
`favicon`	`"favicon.svg"`	Favicon path under your site’s `static/` directory
`ogImage`	`"og.svg"`	Open Graph image path under your site’s `static/` directory
`showExplorer`	`true`	Render the file explorer and mobile drawer
`showBufferline`	`true`	Render the bufferline above the workspace

To ship a quieter layout, turn off either chrome region:

Keybindings and Commands

Fri, 05 Jun 2026 00:00:00 +0000

Keyboard interaction is progressive enhancement. Links and forms still work without JavaScript.

The interface has three modes: NORMAL, COMMAND, and SEARCH.

Keymap

Key	Action
`j` / `k`	Move selection or scroll the active buffer
`g` `g`	Jump to the top
`G`	Jump to the bottom
`/`	Open search palette
`:`	Open command mode
`Enter`	Open the selected row
`q`	Close the current buffer and navigate to the nearest buffer
`b`	Go to the homepage
`Ctrl+d`	Scroll down half a page
`Ctrl+u`	Scroll up half a page
`Ctrl+b`	Scroll up one page
`?`	Open help
`Esc`	Return to normal mode, close help, or close the file explorer

Linewise does not intercept Ctrl+f; browser page search keeps working.

Comments

Thu, 04 Jun 2026 00:00:00 +0000

Linewise supports comments through a provider setting. It ships with giscus, a system that stores discussions in your GitHub repository. Comments are disabled by default.

Setup

Choose your provider in hugo.toml. The default is "none".

[params.linewise.comments]
provider = "none"

Using giscus

You need a public GitHub repository with Discussions enabled, plus four identifiers from the giscus configuration page.

1. Enable Discussions: go to your repo on GitHub, open Settings -> Features -> Discussions, check the box, and save.

Upgrading Linewise

Wed, 03 Jun 2026 00:00:00 +0000

Linewise ships as a Hugo theme. Your posts and site configuration stay in your Hugo site; theme code lives under themes/linewise or in a Hugo module.

If installed as a git submodule

Update the theme repository:

cd themes/linewise
git fetch --tags
git checkout v0.2.0
cd ../..
hugo

Then commit the submodule pointer from your site repository:

git add themes/linewise
git commit -m "chore: update linewise theme"

If installed as a Hugo module

Update the module version:

Release Checklist

Tue, 02 Jun 2026 00:00:00 +0000

Use this checklist before tagging a Hugo theme release.

Pick the version

Choose the next semantic version, for example 0.2.0.

There is no separate version file. The git tag is the source of truth for Linewise releases.

Run checks

pnpm lint
pnpm format:check
pnpm build
pnpm test

Review theme metadata

Check these files before tagging:

theme.toml
go.mod
README.md
images/screenshot.png
exampleSite/content/posts/theme-reference.md

Check upgrade notes

Document breaking changes when any of these change:

Find

Mon, 01 Jan 0001 00:00:00 +0000

Help

Mon, 01 Jan 0001 00:00:00 +0000

Linewise keeps navigation close to Vim’s muscle memory.

Key	Action
`j` / `k`	Move selection
`Enter`	Open selected item
`gg` / `G`	First or last item
`/`	Open search palette
`:`	Command mode
`b`	Buffer list
`Ctrl+d/u`	Scroll half page
`Ctrl+b`	Scroll page up
`q`	Quit current context
`Esc`	Normal mode

Browser page search stays on Ctrl+f.