diff --git a/CHANGELOG.md b/CHANGELOG.md index e174e7c..74fc14d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,13 +5,17 @@ All notable changes to OINK are documented here. The project follows ## [Unreleased] +## [1.3.1] — 2026-10-17 + +Readability repairs and an opt-in FileTree comment layout, with a refreshed +Hugo and Sass toolchain. + ### Changed - Advance the minimum and sole development, CI, and release-test baseline to Hugo Extended 0.168.0. - Refresh homepage and RSS output goldens for Hugo's generator-tag placement and automatic summaries that extend to preserve balanced HTML containers. - - Compile main and ReDoc styles with standalone Dart Sass 1.105.2, preserving project-variable hooks and the separate Font Awesome stylesheet. Install Dart Sass on `PATH` before building. The four known Bootstrap/import-scope @@ -29,6 +33,25 @@ All notable changes to OINK are documented here. The project follows bounded descriptions inside a horizontal scroll region. Ordinary tables, field lists, and static outputs retain their existing layout. +- Add `wrap=true` to FileTree fences for complete long comments, including + unbroken identifiers. The default `wrap=false` preserves compact rows; + filenames, folding, divider controls, mobile stacking, and Print behavior + retain their existing contracts. Invalid values warn and fall back to false. + +### Contributors + +Thanks to [@imbajin](https://github.com/imbajin) for reporting and contributing +these readability repairs, together with fixtures, tests, and bilingual docs: + +- [#48](https://github.com/pgsty/oink/pull/48): Markmap text colors across appearances. +- [#50](https://github.com/pgsty/oink/pull/50): fixed TOC clearance above the footer. +- [#52](https://github.com/pgsty/oink/pull/52): complete FileTree comments, integrated + behind the optional `wrap` parameter. +- [#54](https://github.com/pgsty/oink/pull/54): readable technical table widths, + integrated through the explicit `.td-table--wide` modifier. +- [Documentation #11](https://github.com/pgsty/oink.pgsty.com/pull/11): companion + design contracts and regression coverage. + ## [1.3.0] — 2026-10-15 Resource-backed Expo albums with shared navigation, an original-image viewer, @@ -2291,7 +2314,8 @@ fail the build with the new name rather than being silently ignored. responsive shell rails, improved footer/hero/blog layouts, and accessibility repairs. -[Unreleased]: https://github.com/pgsty/oink/compare/v1.3.0...HEAD +[Unreleased]: https://github.com/pgsty/oink/compare/v1.3.1...HEAD +[1.3.1]: https://github.com/pgsty/oink/compare/v1.3.0...v1.3.1 [1.3.0]: https://github.com/pgsty/oink/compare/v1.2.0...v1.3.0 [1.2.0]: https://github.com/pgsty/oink/compare/v1.1.0...v1.2.0 [1.1.0]: https://github.com/pgsty/oink/compare/v1.0.0...v1.1.0 diff --git a/README.md b/README.md index 241a420..9291ff6 100644 --- a/README.md +++ b/README.md @@ -62,10 +62,10 @@ print and RSS for publication, semantic Markdown for reuse, and optional JavaScript; interaction, accessibility, responsive behavior, print, and machine-readable outputs are tested as separate contracts. -OINK 1.3.0 adds the Expo image-album shell and improves navigation, Landing, -and aggregate Print output. Unreleased development now requires Hugo Extended -0.168.0 and Dart Sass 1.105.2; v1.3.0 retains its original toolchain. See the -[changelog](CHANGELOG.md) for the complete release notes. +OINK 1.3.1 improves Markmap contrast, footer clearance, technical table widths, +and optional FileTree comment wrapping. It requires Hugo Extended 0.168.0 and +standalone Dart Sass 1.105.2. See the [changelog](CHANGELOG.md) for the fixes, +upgrade requirements, and contributor credits. ## Start a site diff --git a/assets/scss/td/_filetree.scss b/assets/scss/td/_filetree.scss index 54364cd..23322db 100644 --- a/assets/scss/td/_filetree.scss +++ b/assets/scss/td/_filetree.scss @@ -295,6 +295,24 @@ text-overflow: ellipsis; } +// Authors can trade compact rows for complete comments; names keep ellipsis. +.td-filetree--wrap { + .td-filetree__row { + block-size: auto; + min-block-size: var(--td-filetree-row); + } + + .td-filetree__comment { + white-space: normal; + } + + .td-filetree__comment-text { + overflow: visible; + text-overflow: clip; + overflow-wrap: anywhere; + } +} + // Narrow viewports: the comment drops under the name instead of truncating. @include media-breakpoint-down(sm) { .td-filetree__row { diff --git a/bin/check-content-primitives.py b/bin/check-content-primitives.py index 48f6640..d8684d8 100755 --- a/bin/check-content-primitives.py +++ b/bin/check-content-primitives.py @@ -10,7 +10,7 @@ from __future__ import annotations import argparse -from html import unescape +from html import escape, unescape from pathlib import Path import re import tempfile @@ -169,6 +169,34 @@ def check_outputs(public: Path) -> list[str]: require(any(">Site tree

" in tree and "", errors) + # Keep full descriptions in the actual row text in every output, including + # CJK and unbroken tokens. Layout/resize checks live in the sibling site's + # FileTree browser suite; text presence alone cannot detect CSS clipping. + for language, suffix in (("", ""), ("zh/", ".zh")): + source = (FIXTURE / f"content/fixtures/filetree-comments{suffix}.md").read_text() + comments = re.findall(r" # (.+)$", source, re.MULTILINE) + comment_page = (public / language / "fixtures/filetree-comments/index.html").read_text() + comment_markdown = (public / language / "fixtures/filetree-comments/index.md").read_text() + comment_print = (public / language / "_print/fixtures/index.html").read_text() + rendered = re.findall(r'([^<]*)', comment_page) + require(len(comments) == 8 and rendered == [escape(text) for text in comments], + f"{language}FileTree long comments are missing from row text", errors) + require(comment_page.count('data-td-filetree-divider') == 4, + f"{language}FileTree long-comment fixtures lost their native dividers", errors) + require(comment_page.count('class="td-filetree td-filetree--wrap"') == 2, + f"{language}FileTree wrap must opt in only the two wrap=true trees", errors) + require(comment_page.count('class="td-filetree"') == 2, + f"{language}FileTree missing/false wrap must retain compact markup", errors) + require(comment_markdown.count('wrap=true}') == 2 and comment_markdown.count('wrap=false}') == 1, + f"{language}FileTree Markdown lost explicit wrap values", errors) + require("td-filetree--wrap" not in comment_print, + f"{language}FileTree screen wrapping must not change static Print markup", errors) + for text in comments: + require(text in comment_markdown, + f"{language}FileTree Markdown lost long comment {text}", errors) + require(f'{escape(text)}' in comment_print, + f"{language}FileTree Print lost long comment {text}", errors) + # --- Native list forms: cards / gallery + filetree fences (lists fixture) -- for marker in ( '
@@ -1514,17 +1517,21 @@

Release assets<

-

21 - Gallery

+

21 - File tree comments

+

Storage directory comments

  • rocksdb-data/
    • data/
      • m/schema store: property keys, vertex/edge/index labels, counters
      • g/graph store: vertices, edges, index tables, olap tables
      • s/system store: tasks, server info, backend meta (driver version)
    • wal/
      • m/
      • g/
      • s/

Unbroken comment

  • storage/
    • id.txtabcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789

Compact comments

  • compact/
    • config.ymlAn explicitly compact description stays on one line even when the text is too long for its column.

Wrapped comments

  • wrapped/
    • a-deliberately-long-runbook-filename-for-a-failover-drill.mdComplete recovery procedure: verify the previous leader, inspect replication, and only then promote the standby.
    • graph/Graph storage: vertices, edges, index tables, and OLAP analysis data all remain readable.
      • metadata.ymlBackend metadata and driver version for the current storage engine.
+
+
+

22 - Gallery

Regression fixtures for a static-first responsive image Gallery.
-

22 - Gallery with Zoom disabled

+

23 - Gallery with Zoom disabled

Gallery remains complete when page-level Image Zoom is disabled.
-

23 - Release assets with an explicit base

+

24 - Release assets with an explicit base

Asset tables can remain useful outside release pages without inventing version facts.
@@ -1554,7 +1561,7 @@

23 - Release assets with an explici

-

24 - Table layout policy

+

25 - Table layout policy

Ordinary prose

@@ -1697,7 +1704,7 @@

-

25 - Unpublished download demo

+

26 - Unpublished download demo

Pinned release facts remain visible without exposing download actions.
diff --git a/tests/goldens/rss/fixtures.xml b/tests/goldens/rss/fixtures.xml index 344bf59..78e50e0 100644 --- a/tests/goldens/rss/fixtures.xml +++ b/tests/goldens/rss/fixtures.xml @@ -128,6 +128,13 @@ +File tree comments +https://example.org/fixtures/filetree-comments/ +Mon, 01 Jan 0001 00:00:00 +0000 +https://example.org/fixtures/filetree-comments/ +<pre class="td-filetree-source"><code class="language-filetree">rocksdb-data/ data/ m/ # schema store: property keys, vertex/edge/index labels, counters g/ # graph store: vertices, edges, index tables, olap tables s/ # system store: tasks, server info, backend meta (driver version) wal/ m/ g/ s/</code></pre><pre class="td-filetree-source"><code class="language-filetree">storage/ id.txt # abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789</code></pre><pre class="td-filetree-source"><code class="language-filetree">compact/ config.yml # An explicitly compact description stays on one line even when the text is too long for its column.</code></pre><pre class="td-filetree-source"><code class="language-filetree">wrapped/ a-deliberately-long-runbook-filename-for-a-failover-drill.md # Complete recovery procedure: verify the previous leader, inspect replication, and only then promote the standby. graph/ # Graph storage: vertices, edges, index tables, and OLAP analysis data all remain readable. metadata.yml # Backend metadata and driver version for the current storage engine.</code></pre> + + Gallery https://example.org/fixtures/gallery/ Mon, 01 Jan 0001 00:00:00 +0000 diff --git a/tests/site/content/fixtures/filetree-comments.md b/tests/site/content/fixtures/filetree-comments.md new file mode 100644 index 0000000..88e9cb1 --- /dev/null +++ b/tests/site/content/fixtures/filetree-comments.md @@ -0,0 +1,33 @@ +--- +title: File tree comments +type: docs +--- + +```filetree {title="Storage directory comments"} +rocksdb-data/ + data/ + m/ # schema store: property keys, vertex/edge/index labels, counters + g/ # graph store: vertices, edges, index tables, olap tables + s/ # system store: tasks, server info, backend meta (driver version) + wal/ + m/ + g/ + s/ +``` + +```filetree {title="Unbroken comment" wrap=true} +storage/ + id.txt # abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789 +``` + +```filetree {title="Compact comments" wrap=false} +compact/ + config.yml # An explicitly compact description stays on one line even when the text is too long for its column. +``` + +```filetree {title="Wrapped comments" wrap=true} +wrapped/ + a-deliberately-long-runbook-filename-for-a-failover-drill.md # Complete recovery procedure: verify the previous leader, inspect replication, and only then promote the standby. + graph/ # Graph storage: vertices, edges, index tables, and OLAP analysis data all remain readable. + metadata.yml # Backend metadata and driver version for the current storage engine. +``` diff --git a/tests/site/content/fixtures/filetree-comments.zh.md b/tests/site/content/fixtures/filetree-comments.zh.md new file mode 100644 index 0000000..b986d14 --- /dev/null +++ b/tests/site/content/fixtures/filetree-comments.zh.md @@ -0,0 +1,33 @@ +--- +title: 文件树注释 +type: docs +--- + +```filetree {title="存储目录注释"} +rocksdb-data/ + data/ + m/ # 元数据存储：属性键、顶点标签、边标签、索引标签和计数器 + g/ # 图数据存储：顶点、边、索引表，以及 OLAP 分析任务使用的数据表 + s/ # 系统存储：任务、服务器信息，以及包括驱动版本在内的后端元数据 + wal/ + m/ + g/ + s/ +``` + +```filetree {title="无空格注释" wrap=true} +storage/ + id.txt # abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789 +``` + +```filetree {title="紧凑注释" wrap=false} +compact/ + config.yml # 显式关闭换行后，较长的配置说明仍然保持单行，并在当前注释列的边界处显示省略号。 +``` + +```filetree {title="换行注释" wrap=true} +wrapped/ + a-deliberately-long-runbook-filename-for-a-failover-drill.md # 完整恢复流程：先确认原主节点状态，再检查复制进度，最后才将备用节点提升为主节点。 + graph/ # 图存储：顶点、边、索引表，以及 OLAP 分析任务使用的数据表，全部保持完整可读。 + metadata.yml # 当前存储引擎的后端元数据与驱动版本。 +```