Filename convention

There are two ways to mark content language:

content/posts/foo.md          # default language
content/posts/foo.zh-cn.md    # Chinese version
content/posts/foo.en.md       # explicit English (when default is zh-cn)

Or use directory layout:

content/en/posts/foo.md
content/zh-cn/posts/foo.md

The theme works with either; pick the one that matches your editing flow.

Language switcher

The header has a language toggle. It only appears for pages that have a translation. If a Chinese post has no English version, the toggle is hidden on the Chinese page — no broken links, no stub pages.

i18n strings

UI strings live in i18n/<lang>.toml. The theme ships with en.toml and zh-cn.toml. To add a new language:

cp themes/inkstone/i18n/en.toml i18n/ja.toml
# Then translate the values inside

Add the language to your site config:

[languages.ja]
  label = "日本語"
  locale = "ja"
  weight = 3
  [languages.ja.params]
    description = "..."

Reading time

Reading time is calculated per language using Hugo’s WordCount and ReadingTime. With hasCJKLanguage = true set, CJK pages report 501 chars/minute; non-CJK pages report 213 words/minute. The theme reads the page’s actual language and uses the right formula automatically.

That’s the multilingual model in a nutshell. For the underlying patterns, see Hugo’s language management docs↗ .

What Inkstone does for CJK

1. Word counting respects characters, not whitespace tokens. With hasCJKLanguage = true set site-wide, Hugo’s .WordCount counts CJK characters individually instead of trying (and failing) to whitespace-tokenize them.
2. Reading time uses 501 chars/min on CJK pages, the constant Hugo derives from CJK reading speed studies. Latin pages stay on the 213 word/min default.
3. Font stack prefers LXGW WenKai, falling back through Noto Serif SC to system serif — chosen to keep CJK and Latin glyphs at compatible weights.
4. Line-height bumps to 1.7 on CJK pages (vs. 1.6 for pure Latin) to compensate for taller character bodies.

Why this matters in practice

Mixed-script paragraphs are where naive themes break. A sentence like “我读了 Borges 的 Ficciones” has three writing systems and an italic stretch — and most themes either let the browser produce a fake oblique on CJK glyphs (ugly) or force a single font for everything (worse).

Inkstone scopes font-style: normal to the CJK-detected ranges in prose, so the Latin italics still render properly while the CJK characters stay upright in their natural form.

Punctuation and spacing

The .prose region opts into:

• font-feature-settings: "palt" for proportional alternates on CJK punctuation — ， 。 ？ ！ collapse the half-em “air” they ship with by default.
• text-spacing-trim to handle leading/trailing punctuation at line breaks.
• A 0.15em soft gap between CJK characters and adjacent Latin/numeric runs (Pangu-style), scoped to prose only — UI chrome is left alone.

Try it on a real Chinese post

The translation of this post — 03-cjk-mixed.zh-cn.md — is where you can actually see the typography work. Switch the language toggle to view it.

content/posts/03-cjk-mixed.md         # this English post
content/posts/03-cjk-mixed.zh-cn.md   # the Chinese demo post

Summary

If you write a lot of bilingual prose, Inkstone aims to remove the typography distractions so you can focus on what the words are doing. Most of these decisions are scoped to .prose and won’t bleed into UI chrome, so they’re safe to compose with other themes’ design tokens if you fork.

Headings

The theme uses LXGW WenKai for body text in CJK contexts and falls back to Noto Serif SC and system serif fonts. Headings inherit the same family by default but can be re-styled per project via assets/css/variable.css design tokens.

Third-level heading

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Fourth-level heading

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Paragraph spacing

The default rhythm is 1.6× line-height with a comfortable max-width that keeps line length around 65–75 characters. This is tuned for desktop reading; on mobile the layout collapses to a single column with adjusted spacing.

For mixed CJK/Latin text, the theme bumps line-height slightly to accommodate the taller character box of Chinese glyphs without making English paragraphs feel airy.

Lists

Unordered:

• First item with a meaningful sentence about something
• Second item that demonstrates how the bullet styling looks
• Third item just for completeness
  • Nested item one
  • Nested item two

Ordered:

1. Numbered items use a slightly different rhythm
2. The numbers themselves are styled to match the prose color
3. Nested ordered lists work too:
   1. Indented one
   2. Indented two

Inline elements

Here’s a sentence with inline code, bold text, italic text, and a link to the source↗ . The link gets an external-link mark automatically when it points off-domain.

Blockquotes

Reading is to the mind what exercise is to the body.

— Joseph Addison

Code blocks

def fibonacci(n: int) -> int:
    """Classic recursive fib — please don't use this in production."""
    if n < 2:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)


if __name__ == "__main__":
    print([fibonacci(i) for i in range(10)])

const debounce = (fn, ms = 250) => {
  let t;
  return (...args) => {
    clearTimeout(t);
    t = setTimeout(() => fn(...args), ms);
  };
};

Tables

Pullquote

A classic is a book that has never finished saying what it has to say. — Italo Calvino

That’s the gist. For a complete shortcode catalog, see the Shortcodes demo .

Why Inkstone?

Inkstone is built around three convictions:

1. Reading is the primary mode. Every layout decision serves the reader, not the author’s ego.
2. Bilingual is the default. Mixed Chinese/English content gets proper line-height, character-counted reading time, and a font fallback chain that doesn’t render Latin glyphs in a CJK font.
3. Progressive enhancement is non-negotiable. Search, lightbox, theme toggle all degrade gracefully when JS is disabled.

Built-in shortcodes

Inkstone ships with 25+ content shortcodes. The most common ones:

• Callouts and admonitions — Five severity levels (note, tip, warning, danger, success) with i18n-aware labels
• Galleries — Justified grid + lightbox, configured via JSON data
• Code blocks — Highlighted with Chroma, with optional copy button and line numbers
• Diagrams — Mermaid and Markmap rendered client-side via CDN
• Math — MathJax v4, only loaded on pages that actually use math

For the full reference with live examples, see the Shortcodes demo page .

What’s next

Browse the Posts section for more samples, or jump directly to the Shortcodes demo for the full reference.