mirror of https://github.com/theNewDynamic/gohugo-theme-ananke.git

Patrick Kollitsch
16 hours ago daca88d9ec3fb681188993378ce3eeb5c1105083
feat(styles): add hyphenation utility for post content (#1128)

Adds a `hyphenate` utility class, because Tachyons has no hyphenation
classes, and applies it to single-page content (`layouts/single.html`
and `layouts/page/single.html`).

* `hyphens: auto` with `hyphenate-limit-chars: 6 3 3`.
* Headings, inline code, `kbd`, and `samp` keep their words whole; code
blocks keep `hyphens: none`.
* Sites change or disable it by redefining `.hyphenate` in
`ananke.custom_css`, for example `.hyphenate { hyphens: manual; }`.
* `DESIGN.md` lists the class in the typography section.

Documentation: `gohugo-ananke/documentation` branch `docs/hyphenation`
(styles guide and custom CSS guide).

## Validation

* `npm test`: 57/57 with Hugo 0.160.0 and 0.170.1.
* `npm run test:coverage-gate`: passes (no new parameter).
* `npx playwright test`: 109 passed, including the new
`tests/e2e/hyphenation.spec.ts`; the hyphenation spec also passes with
Hugo 0.160.0.
* Lint results are unchanged from v2.22.0. Visual snapshots: the same 8
of 12 fail on v2.22.0 and on this branch.
* Rendered hyphenation confirmed in Firefox. Playwright's Chromium build
has no hyphenation dictionaries, so it shows no visual change.

* [x] Added or updated feature fixtures and tests, and registered
parameters and shortcodes in `tests/catalog.yaml` (or explained why no
tests are needed). No new parameter or shortcode, so no catalogue entry;
added `tests/e2e/hyphenation.spec.ts`.
4 files modified
1 files added
56 ■■■■■ changed files
DESIGN.md 2 ●●●●● patch | view | raw | blame | history
assets/ananke/css/_styles.css 20 ●●●●● patch | view | raw | blame | history
layouts/page/single.html 2 ●●●●● patch | view | raw | blame | history
layouts/single.html 2 ●●●●● patch | view | raw | blame | history
tests/e2e/hyphenation.spec.ts 30 ●●●●● patch | view | raw | blame | history
DESIGN.md
@@ -275,7 +275,7 @@
Tachyons typography utilities define the scale and families. Ananke's defaults layer these choices on top:
* **Body shell:** `avenir` with `bg-near-white` on the `<body>`.
* **Article body:** `serif f4 lh-copy nested-links`, overridable with `post_content_classes`.
* **Article body:** `serif f4 lh-copy nested-links`, overridable with `post_content_classes`. Single-page content also has `hyphenate`, Ananke's own hyphenation utility in `_styles.css` (Tachyons has none); sites redefine the class in custom CSS to change or disable it.
* **Headlines:** `athelas` for article and summary headings; site hero headings use lightweight sans-serif (`fw2`).
* **Navigation:** lightweight sans-serif with responsive sizes (`f5 f4-ns` for menu items and `f3 fw2` for the site title/logo text).
* **Metadata:** `helvetica tracked ttu` and small text sizes for section labels, dates, reading time, and word count.
assets/ananke/css/_styles.css
@@ -26,6 +26,26 @@
}
/* ------------------------------------------------------------------ *
 * Hyphenation utility (Tachyons has none)
 *
 * Browsers hyphenate only text in a language they have a dictionary
 * for; baseof.html sets `lang` from the site locale. Words need six
 * letters, with three on each side of the break. Headings and code
 * keep their words whole. Sites change or disable this by redefining
 * `.hyphenate` in ananke.custom_css, for example
 * `.hyphenate { hyphens: manual; }`.
 * ------------------------------------------------------------------ */
.hyphenate {
  hyphens: auto;
  hyphenate-limit-chars: 6 3 3;
}
.hyphenate :where(h1, h2, h3, h4, h5, h6, code, kbd, samp) {
  hyphens: manual;
}
/* ------------------------------------------------------------------ *
 * Header navigation (see layouts/_partials/site-navigation.html)
 *
 * Colours, type, and spacing come from Tachyons classes in the template;
layouts/page/single.html
@@ -16,7 +16,7 @@
          {{ .Title }}
        </h1>
      </header>
      <div class="nested-copy-line-height lh-copy f4 nested-links {{ $.Param "text_color" | compare.Default "mid-gray" }}">
      <div class="nested-copy-line-height lh-copy hyphenate f4 nested-links {{ $.Param "text_color" | compare.Default "mid-gray" }}">
        {{- partials.Include "hook.html" (dict "hook" "content-before" "context" .) -}}
        {{ .Content }}
        {{- partials.Include "hook.html" (dict "hook" "content-after" "context" .) -}}
layouts/single.html
@@ -60,7 +60,7 @@
        <span class="f6 mv4 dib tracked"> - {{ lang.Translate "wordCount" .WordCount }} </span>
      {{ end }}
    </header>
    <div class="nested-copy-line-height lh-copy {{ $.Param "post_content_classes"  | compare.Default "serif"}} f4 nested-links {{ $.Param "text_color" | compare.Default "mid-gray" }} {{ compare.Conditional (compare.Eq $.Site.Language.Direction "rtl") "pl4-l" "pr4-l" }} {{ if $needs_aside }}w-two-thirds-l{{ else }}w-100-l{{ end }}">
    <div class="nested-copy-line-height lh-copy hyphenate {{ $.Param "post_content_classes"  | compare.Default "serif"}} f4 nested-links {{ $.Param "text_color" | compare.Default "mid-gray" }} {{ compare.Conditional (compare.Eq $.Site.Language.Direction "rtl") "pl4-l" "pr4-l" }} {{ if $needs_aside }}w-two-thirds-l{{ else }}w-100-l{{ end }}">
      {{- partials.Include "hook.html" (dict "hook" "content-before" "context" .) -}}
      {{- .Content -}}
      {{- partials.Include "hook.html" (dict "hook" "content-after" "context" .) -}}
tests/e2e/hyphenation.spec.ts
New file
@@ -0,0 +1,30 @@
import { expect, test } from "@playwright/test";
const POST = "/posts/hello/";
const hyphens = (selector: string) => (page: import("@playwright/test").Page) =>
  page
    .locator(selector)
    .first()
    .evaluate((element) => getComputedStyle(element).hyphens);
test.describe("hyphenation utility", () => {
  test("hyphenates post paragraphs in the page language", async ({ page }) => {
    await page.goto(POST);
    await expect(page.locator("html")).toHaveAttribute("lang", /.+/);
    await expect(page.locator("article .hyphenate")).toHaveCount(1);
    expect(await hyphens("article .hyphenate p")(page)).toBe("auto");
  });
  test("keeps code words whole", async ({ page }) => {
    await page.goto(POST);
    expect(await hyphens("article .hyphenate p code")(page)).toBe("manual");
    expect(await hyphens("article .hyphenate pre")(page)).toBe("none");
  });
  test("site CSS can redefine the class", async ({ page }) => {
    await page.goto(POST);
    await page.addStyleTag({ content: ".hyphenate { hyphens: manual; }" });
    expect(await hyphens("article .hyphenate p")(page)).toBe("manual");
  });
});