Skip to content

docs(blocks): add numbered split layout example for approach - #131

Merged
markdumay merged 2 commits into
mainfrom
feat/approach-numbered-split
Jul 28, 2026
Merged

docs(blocks): add numbered split layout example for approach#131
markdumay merged 2 commits into
mainfrom
feat/approach-numbered-split

Conversation

@markdumay

@markdumay markdumay commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

Summary

Documents the approach Bookshop component's new opt-in arguments, shipped in gethinode/mod-blocks v2.3.0 (PR #181):

  • layout: "split" — renders the heading in a left column with the elements as a vertically stacked list on the right (50-50 on md+, stacked on mobile), instead of the card grid.
  • numbered: true — auto-numbers elements with a digit badge instead of a per-element icon; the digit is resolved through the site's configured Font Awesome family (site.Params.modules.fontawesome.defaultFamily).

Adds a new ### Numbered split layout subsection to content/blocks/approach.md, combining both arguments in one example, following the same per-variant pattern already used for the articles block's layout: magazine example (commit 2e86551): short prose intro + a fenced {{< example-bookshop lang="bookshop" >}} block, placed before ## Arguments.

Smoke-test evidence

mod-docs' own exampleSite deliberately does not mount content/blocks/*.md (it only imports this module's layouts/dist, not content/data — confirmed by inspecting exampleSite/hugo.toml), so it can't render this example live. Per review feedback, I smoke-tested against gethinode/hinode's own exampleSite, which does import mod-docs with content mounted at content/docs alongside mod-blocks/v2:

  • Locally wired hinode's exampleSite/go.mod with a replace to this branch's worktree and bumped mod-blocks/v2 to v2.3.0, built with hugo --gc --minify -s exampleSite, then reverted every change (git status clean, nothing left behind — this was a read-only smoke test of a shared checkout).
  • Confirmed the rendered /en/docs/blocks/approach/ page contains the intended split-layout markup: approach-steps / approach-step / approach-number classes present, heading correctly split into the left column with the display-5/text-start mb-0 treatment.

One real finding, not a docs bug: on hinode's own exampleSite, defaultFamily is configured to "bi" (Bootstrap Icons) — a realistic, already-live site configuration. Bootstrap Icons has no bare digit icon names (only compound ones like 1-circle/1-square), so the numbered digit glyph resolves to assets/svgs/bi/1.svg and similar, which don't exist, leaving the approach-number circle empty (Hugo logs Cannot find icon: assets/svgs/bi/1.svg etc.). This is a mod-blocks component defect (the bare-digit-name design assumes every icon family ships plain numeric glyphs, which isn't true for Bootstrap Icons), not something this docs page can paper over — the example demonstrates correct, minimal component syntax. Reported separately for a mod-blocks follow-up; not fixed here per review guidance (docs changes shouldn't silently work around upstream component bugs).

Verification

  • pnpm run lint:markdown — zero new issues from this change (21 pre-existing issues remain in three unrelated files: preview.md, testimonials.md, components/testimonial.md; confirmed identical on a clean main checkout, not introduced here). pnpm run lint:styles passes trivially (no SCSS touched).
  • pnpm run build (hugo --gc --minify -s exampleSite) clean, 0 errors (unaffected by this content change, since content/blocks/*.md isn't part of this repo's own exampleSite build scope — see above).
  • Husky pre-commit (pnpm test) and commit-msg (commitlint) both passed on commit.

🤖 Generated with Claude Code

markdumay and others added 2 commits July 28, 2026 16:22
Document the mod-blocks approach component's new opt-in arguments
(gethinode/mod-blocks#181): layout: split renders the heading beside
a vertically stacked element list instead of the card grid, and
numbered: true auto-numbers elements with a digit badge resolved
through the site's configured Font Awesome family.

Follows the same per-variant subsection pattern used for the
articles block's magazine layout example (commit 2e86551): a short
prose intro plus a fenced example-bookshop block, placed before the
Arguments section.

The exampleSite here only mounts mod-docs' layouts (not its content
or data), so it never renders content/blocks/*.md and can't
exercise this example live; pnpm test (the exampleSite build) and
pnpm run lint:markdown both pass, and lint:markdown reports zero new
issues introduced by this change (21 pre-existing issues remain in
unrelated files: preview.md, testimonials.md, components/
testimonial.md — not gated by CI, which only runs pnpm test).

Does not depend on a release: mod-blocks#181 is still open, and this
docs change is intentionally left unpushed until it ships.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Update the approach block's numbered split-layout example to give
each element an explicit icon (1-circle/2-circle/3-circle, the same
set already used in this page's default example) rather than relying
on the bare-digit fallback.

Follows the mod-blocks fix that makes numbered: true prefer an
element's own icon over the auto-digit fallback, and documents why:
the digit fallback only shows a glyph when the resolved icon family
ships plain digit names (Font Awesome does; Bootstrap Icons does
not, hence the explicit icons here).

Re-verified via the hinode exampleSite harness (same read-only
scaffolding + full-revert discipline as the prior smoke test, this
time replacing both mod-docs and mod-blocks to their local unpushed
worktrees): the rendered page now shows real bi-1-circle/bi-2-circle/
bi-3-circle glyphs inside the approach-number badges, confirming the
docs example works correctly on hinode's own bi-default site.

pnpm run lint:markdown clean on this file (21 pre-existing issues
remain in unrelated files, unchanged). pnpm build clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@markdumay
markdumay merged commit 812211e into main Jul 28, 2026
8 checks passed
@markdumay
markdumay deleted the feat/approach-numbered-split branch July 28, 2026 16:37
@markdumay

Copy link
Copy Markdown
Contributor Author

🎉 This PR is included in version 1.15.6 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant