Skip to content

feat(docs): adopt txn2 design system for docs site #77

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cjimti merged 2 commits into from
Apr 27, 2026
Merged

feat(docs): adopt txn2 design system for docs site #77

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
53c2514
feat(docs): adopt txn2 design system for docs site
cjimti Apr 27, 2026
ec2b905
fix(docs): address review findings on design system PR
cjimti Apr 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 115 additions & 0 deletions DESIGN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
---
version: alpha
spec: https://github.com/google-labs-code/design.md
name: txeh-docs
description: Local design adoption record for the txeh.txn2.com documentation site. References txn2/www DESIGN.md as the canonical visual identity for tokens, typography, components, voice, and accessibility rules. Records only the decisions and MkDocs Material learnings that the canonical does not cover.
upstream:
design: https://github.com/txn2/www/blob/master/DESIGN.md
tokens: https://github.com/txn2/www/blob/master/tokens.json
adoption: token-alignment
stack:
generator: MkDocs
theme: Material for MkDocs
templates: docs/overrides/
styles: docs/stylesheets/extra.css
---

## What is canonical

The canonical visual identity for txn2 lives in [`txn2/www/DESIGN.md`](https://github.com/txn2/www/blob/master/DESIGN.md) with tokens in [`txn2/www/tokens.json`](https://github.com/txn2/www/blob/master/tokens.json). This file defers to those for everything below. If a value here disagrees with upstream, upstream wins.

| Concern | Source of truth |
|----------------------|-----------------|
| Color palette | upstream `tokens.json` `color.*` |
| Typography stack | upstream `tokens.json` `font.*` |
| Type scale | upstream `DESIGN.md` Typography table |
| Spacing / measure | upstream `tokens.json` `size.*` |
| Component contracts | upstream `DESIGN.md` Components |
| Voice / copy rules | upstream `DESIGN.md` Voice and Copy |
| Accessibility rules | upstream `DESIGN.md` Do's and Don'ts |
| Mermaid theme | upstream `DESIGN.md` `mcp__card--feature` block |

Tokens are mirrored as CSS custom properties in `docs/stylesheets/extra.css` `:root`. They are duplicated for runtime use, not as a divergence point. When upstream changes a token, update the value in `extra.css` and ship.

## Adoption level: token alignment

Per the upstream downstream contract, three levels are valid:

1. Reference. Link to upstream, no visual changes.
2. Token alignment. Keep MkDocs Material, re-skin via `extra.css` against upstream tokens.
3. Full re-skin. Replace MkDocs Material with custom layouts.

txeh runs at **level 2**, matching its sister project kubefwd. The site keeps Material's instant nav, search, sidebar, version selector, code copy, and content extensions. The visual layer is replaced. The homepage is a custom Material template that takes over `block header`, `block container`, and `block footer` for full-bleed treatment.

## File map

| Path | Role |
|------|------|
| `mkdocs.yml` | Single dark `slate` palette. `font: false` so CSS loads the upstream Google Fonts URL with trimmed axes. |
| `docs/index.md` | Stub front matter with `template: home.html`. All homepage HTML lives in the template. |
| `docs/overrides/main.html` | Adds the upstream Google Fonts `<link>` plus OG and Twitter meta. Inherited by every page. |
| `docs/overrides/home.html` | Custom homepage template. Overrides `block header` (rail), `block tabs` (empty), `block container` (page--home shell with hero, sections, flagship cards, stack, coda), `block footer` (home-footer). |
| `docs/overrides/404.html` | Restyled not-found page. Inherits `main.html`, uses `.page--home` shell so the rail and footer match. |
| `docs/stylesheets/extra.css` | All design rules. Two halves: homepage components scoped under `.page--home`, and Material chrome restyle for inner pages via `[data-md-color-scheme="slate"]` variable overrides. |

## Project-specific components

Components ported from upstream verbatim, with txeh content:

- `.rail` (replaces Material `.md-header` on the homepage). Brand links to `./`. Live UTC clock in meta. txn2.com link in meta as `part of <em class="serif">txn2</em> ↗`.
- `.hero` with three Fraunces rows (txeh / hosts file / management.).
- `.section`, `.section__index`, `.section__title`.
- `.flagship__card`. Two cards: a CLI demo card (`add`, `remove`, `list`, `show`) and a Go library card (`NewHostsDefault`, `AddHost`, `Save`). Top accent line animates on hover per upstream spec.
- `.terminal`, `.terminal__bar`, `.terminal__body` with `.t-prompt`, `.t-ok`, `.t-mute` classes. The only block with shadow.
- `.stack`, `.stack__row`. Each row links to a real anchor in the docs (cli/, library/, api/, troubleshooting/).
- `.coda` and `.home-footer` (renamed from upstream `.footer` to avoid collision with markdown that uses `class="footer"`; see kubefwd Learning #5).

Components from upstream **not used** here, with reason:

- `.mcp__card--feature` and the MCP grid. txeh is a single library, not an MCP catalog.
- The 5-column footer's `sponsors / craig` columns. The txeh home-footer has `about / docs / interfaces / code / txn2 / org` columns instead, since this site is project-scoped.

Custom additions specific to txeh:

- `home-footer__col--meta` includes a `txn2 / org` panel that backlinks to txn2.com explicitly. Per the org-wide rule that every sister project must clearly link home.
- The CLI flagship card's terminal demo uses real `txeh add`, `txeh list ip`, and `txeh remove host` invocations against `127.0.0.1`. The library card shows the `NewHostsDefault` / `AddHost` / `Save` path.

## MkDocs Material learnings

The Material learnings list applies to every MkDocs Material project re-skinned to the txn2 identity. txeh inherits them all from kubefwd. Read the full set in [`txn2/kubefwd/DESIGN.md`](https://github.com/txn2/kubefwd/blob/master/DESIGN.md) "MkDocs Material learnings". Brief summary so this file remains useful in isolation:

1. Override the homepage via a separate template, not via CSS hacks.
2. Re-skin inner pages via Material variable overrides on `[data-md-color-scheme="slate"]`.
3. `font: false` to load fonts directly from CSS.
4. Scope every homepage component class under `.page--home`.
5. Rename `.footer` to `.home-footer` to avoid collision.
6. `h3` and `h4` are technical reference, not display type. Switch them to Instrument Sans bold; flip any heading containing inline code to JetBrains Mono via `:has(code)` with a `@supports not selector(:has(*))` fallback.
7. Tabbed content nests boxes by default. Strip `.tabbed-set` background and border, keep only the label underline.
8. Mermaid via Material's `--md-mermaid-*` CSS variables, not via separate init.
9. Guard inline scripts against `navigation.instant` rehydration. The live UTC clock uses a `window.__txehClock` sentinel.
10. Drop the light/dark toggle. Single `scheme: slate`.
11. Atmospheric overlays at low z-index (grain and vignette at z-index 1, below rail at z-50).
12. Hugo-only token compilation does not exist in MkDocs. Token sync is a manual edit to `extra.css`.

## Voice and copy

Defers to upstream. Briefly:

- No em-dashes (U+2014) or en-dashes (U+2013) anywhere, including code comments and template comments. Use commas, periods, colons, parentheses, slashes, hyphens.
- No AI-tell vocabulary: `seamless`, `leverage`, `comprehensive`, `robust`, `delve`, `unleash`, `elevate`, `embark`, `tapestry`, `not just X but Y`, `as an AI`, `let me X`.
- Sentence case for body. Lowercase for rail and label text. Title case rare.
- Section indices: `§ 01 / title` with slash, never an em-dash.
- Year ranges use a hyphen: `2018-2026`.
- Verify before commit: `grep -RE "—|–" docs/ mkdocs.yml`.

## Updating

When the upstream `txn2/www/DESIGN.md` or `tokens.json` changes:

1. Read the upstream diff. Identify which tokens, components, or rules changed.
2. Update the matching CSS variables in `docs/stylesheets/extra.css` `:root`.
3. If a component contract changed (padding, border, hover behavior), update the homepage template in `docs/overrides/home.html` and the matching CSS rules.
4. Update this file's File map / Project-specific components sections if a new component is added or removed.
5. Run `mkdocs build --strict` and verify in the browser before committing. Verify the home page hero, flagship cards, terminal, stack, coda, and home-footer. Verify an inner page (`/cli/`, `/library/`) still inherits the look.

Keep this file thin. If a section grows past 30 lines, ask whether it belongs upstream instead.
102 changes: 5 additions & 97 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,102 +1,10 @@
---
title: txeh
template: home.html
hide:
- navigation
- toc
- footer
---

<div style="text-align: center; margin: 2rem 0;">
<img src="images/logo.png" alt="txeh" style="max-width: 400px;">
</div>

# txn2/txeh

/etc/hosts management as a Go library and CLI utility. Programmatic and command-line access to add, remove, and query hostname-to-IP mappings. Thread-safe, cross-platform, and built to support tools like [kubefwd](https://github.com/txn2/kubefwd).

[Get Started](getting-started.md){ .md-button .md-button--primary }
[View on GitHub](https://github.com/txn2/txeh){ .md-button }

## Two Ways to Use

<div class="grid cards" markdown>

- :material-console:{ .lg .middle } **Use the CLI**

---

Manage `/etc/hosts` entries from the command line.

- Add, remove, list hostnames
- CIDR range operations
- Dry run mode for previewing changes

[:octicons-arrow-right-24: CLI Reference](cli.md)

- :material-code-braces:{ .lg .middle } **Use the Go Library**

---

Import into your Go application for programmatic hosts file management.

- Thread-safe with mutex locking
- In-memory mode from strings
- Inline comment support

[:octicons-arrow-right-24: Library docs](library.md)

</div>

## Core Features

<div class="grid cards" markdown>

- :material-lock-outline:{ .lg .middle } **Thread-Safe**

---

All public methods use mutex locking for safe concurrent access from multiple goroutines.

- :material-ip-network:{ .lg .middle } **IPv4 & IPv6**

---

Full support for both address families with family-specific lookups.

- :material-select-group:{ .lg .middle } **CIDR Operations**

---

Bulk add and remove hosts by CIDR range. List all entries in a network.

- :material-monitor:{ .lg .middle } **Cross-Platform**

---

Linux, macOS, and Windows. Auto-detects the system hosts file location.

</div>

## Quick Install

=== "Homebrew"

```bash
brew install txn2/tap/txeh
```

=== "Go Install"

```bash
go install github.com/txn2/txeh/txeh@latest
```

=== "Go Library"

```bash
go get github.com/txn2/txeh
```

---

[![CI](https://github.com/txn2/txeh/actions/workflows/ci.yml/badge.svg)](https://github.com/txn2/txeh/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/txn2/txeh/branch/master/graph/badge.svg)](https://codecov.io/gh/txn2/txeh)
[![Go Report Card](https://goreportcard.com/badge/github.com/txn2/txeh)](https://goreportcard.com/report/github.com/txn2/txeh)
[![Go Reference](https://pkg.go.dev/badge/github.com/txn2/txeh.svg)](https://pkg.go.dev/github.com/txn2/txeh)
<!-- Homepage content lives in docs/overrides/home.html. -->
22 changes: 11 additions & 11 deletions docs/overrides/404.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,22 +3,22 @@
{% block content %}
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<h1>Page Not Found</h1>
<p>The page you're looking for doesn't exist or has been moved.</p>
<h1>404 / not found</h1>
<p>That page does not exist, or has moved.</p>

<h2>Quick Links</h2>
<h2>Quick links</h2>
<ul>
<li><a href="{{ config.site_url }}">Home</a></li>
<li><a href="{{ config.site_url }}getting-started/">Getting Started</a></li>
<li><a href="{{ config.site_url }}cli/">CLI Reference</a></li>
<li><a href="{{ config.site_url }}library/">Go Library</a></li>
<li><a href="{{ config.site_url }}api/">API Reference</a></li>
<li><a href="{{ config.site_url }}troubleshooting/">Troubleshooting</a></li>
<li><a href="{{ config.site_url }}">home</a></li>
<li><a href="{{ config.site_url }}getting-started/">getting started</a></li>
<li><a href="{{ config.site_url }}cli/">cli reference</a></li>
<li><a href="{{ config.site_url }}library/">go library</a></li>
<li><a href="{{ config.site_url }}api/">api reference</a></li>
<li><a href="{{ config.site_url }}troubleshooting/">troubleshooting</a></li>
</ul>

<p>Or use the search box above to find what you're looking for.</p>
<p>Or use the search box above to find what you are looking for.</p>

<p><a href="https://github.com/txn2/txeh" class="md-button md-button--primary">View on GitHub</a></p>
<p><a href="https://github.com/txn2/txeh" class="md-button md-button--primary">view on github</a></p>
</article>
</div>
{% endblock %}
Loading
Loading