Move docs to zensical by KevinGimbel · Pull Request #1421 · j178/prek

KevinGimbel · 2026-01-20T09:21:53Z

WIP, moving docs to Zensical.

codecov · 2026-01-20T09:23:53Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.66%. Comparing base (0784ddf) to head (8cc1f61).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1421   +/-   ##
=======================================
  Coverage   90.66%   90.66%           
=======================================
  Files          82       82           
  Lines       16698    16698           
=======================================
  Hits        15140    15140           
  Misses       1558     1558

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

github-actions · 2026-01-20T09:25:17Z

📦 Cargo Bloat Comparison

Binary size change: +0.00% (22.5 MiB → 22.5 MiB)

Expand for cargo-bloat output

Head Branch Results

 File  .text    Size        Crate Name
 0.3%   0.8% 71.4KiB        prek? <prek::cli::Command as clap_builder::derive::Subcommand>::augment_subcommands
 0.3%   0.7% 62.5KiB         prek prek::languages::<impl prek::config::Language>::run::{{closure}}::{{closure}}
 0.2%   0.6% 55.3KiB         prek prek::languages::<impl prek::config::Language>::run::{{closure}}::{{closure}}
 0.2%   0.5% 46.3KiB         prek prek::run::{{closure}}
 0.2%   0.5% 42.7KiB         prek prek::cli::run::run::run::{{closure}}
 0.2%   0.5% 42.7KiB         prek prek::identify::by_extension::{{closure}}
 0.2%   0.4% 35.1KiB         prek prek::languages::<impl prek::config::Language>::install::{{closure}}
 0.1%   0.3% 31.8KiB        prek? <prek::cli::RunArgs as clap_builder::derive::Args>::augment_args
 0.1%   0.3% 30.0KiB  serde_json? <&mut serde_json::de::Deserializer<R> as serde_core::de::Deserializer>::deserialize_struct
 0.1%   0.2% 21.5KiB         prek prek::archive::unzip::{{closure}}
 0.1%   0.2% 21.3KiB clap_builder clap_builder::parser::parser::Parser::get_matches_with
 0.1%   0.2% 19.6KiB         prek <prek::languages::ruby::ruby::Ruby as prek::languages::LanguageImpl>::install::{{closure}}
 0.1%   0.2% 19.3KiB         prek prek::cli::run::filter::collect_files_from_args::{{closure}}
 0.1%   0.2% 18.9KiB         prek prek::cli::run::filter::collect_files_from_args::{{closure}}
 0.1%   0.2% 18.6KiB         ring ring_core_0_17_14__x25519_ge_frombytes_vartime
 0.1%   0.2% 18.3KiB         prek prek::hooks::meta_hooks::check_hooks_apply::{{closure}}
 0.1%   0.2% 18.3KiB         prek prek::hooks::meta_hooks::check_hooks_apply::{{closure}}
 0.1%   0.2% 18.2KiB   hyper_util hyper_util::client::legacy::client::Client<C,B>::send_request::{{closure}}
 0.1%   0.2% 18.1KiB    [Unknown] fe_loose_invert
 0.1%   0.2% 17.7KiB         prek prek::cli::run::filter::collect_files_from_args::{{closure}}
36.6%  91.6%  8.2MiB              And 19831 smaller methods. Use -n N to show more.
40.0% 100.0%  9.0MiB              .text section size, the file size is 22.5MiB

Base Branch Results

 File  .text    Size        Crate Name
 0.3%   0.8% 71.4KiB        prek? <prek::cli::Command as clap_builder::derive::Subcommand>::augment_subcommands
 0.3%   0.7% 62.5KiB         prek prek::languages::<impl prek::config::Language>::run::{{closure}}::{{closure}}
 0.2%   0.6% 55.3KiB         prek prek::languages::<impl prek::config::Language>::run::{{closure}}::{{closure}}
 0.2%   0.5% 46.3KiB         prek prek::run::{{closure}}
 0.2%   0.5% 42.7KiB         prek prek::cli::run::run::run::{{closure}}
 0.2%   0.5% 42.7KiB         prek prek::identify::by_extension::{{closure}}
 0.2%   0.4% 35.1KiB         prek prek::languages::<impl prek::config::Language>::install::{{closure}}
 0.1%   0.3% 31.8KiB        prek? <prek::cli::RunArgs as clap_builder::derive::Args>::augment_args
 0.1%   0.3% 30.0KiB  serde_json? <&mut serde_json::de::Deserializer<R> as serde_core::de::Deserializer>::deserialize_struct
 0.1%   0.2% 21.5KiB         prek prek::archive::unzip::{{closure}}
 0.1%   0.2% 21.3KiB clap_builder clap_builder::parser::parser::Parser::get_matches_with
 0.1%   0.2% 19.6KiB         prek <prek::languages::ruby::ruby::Ruby as prek::languages::LanguageImpl>::install::{{closure}}
 0.1%   0.2% 19.3KiB         prek prek::cli::run::filter::collect_files_from_args::{{closure}}
 0.1%   0.2% 18.9KiB         prek prek::cli::run::filter::collect_files_from_args::{{closure}}
 0.1%   0.2% 18.6KiB         ring ring_core_0_17_14__x25519_ge_frombytes_vartime
 0.1%   0.2% 18.3KiB         prek prek::hooks::meta_hooks::check_hooks_apply::{{closure}}
 0.1%   0.2% 18.3KiB         prek prek::hooks::meta_hooks::check_hooks_apply::{{closure}}
 0.1%   0.2% 18.2KiB   hyper_util hyper_util::client::legacy::client::Client<C,B>::send_request::{{closure}}
 0.1%   0.2% 18.1KiB    [Unknown] fe_loose_invert
 0.1%   0.2% 17.7KiB         prek prek::cli::run::filter::collect_files_from_args::{{closure}}
36.6%  91.6%  8.2MiB              And 19831 smaller methods. Use -n N to show more.
40.0% 100.0%  9.0MiB              .text section size, the file size is 22.5MiB

KevinGimbel · 2026-01-20T09:49:43Z

Snippets

For snippets / markdown includes Zensical uses a tiny scissor marker (--8<--), this also uses different start and end markers. Docs: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation

They have been converted with some regex magic ✨

Snipping markers

mkdocs:

<!-- features:start -->
<!-- features:end -->

Zensical

<!-- --8<-- [start:features] -->
<!-- --8<-- [end:features] -->

Regex to convert with VSCode Find & Replace:

Find: <!--(?<key>.*):start -->
Replace: <!-- --8<-- [start:$1] -->
Find: <!--(?<key>.*):end -->
Replace: <!-- --8<-- [end:$1] -->

include markers

Find: \{%\ninclude-markdown "../(?<file>.*)"\nstart="<!-- (?<key>.*):start -->"\n.*\n%\}
Replace: --8<-- "$1:$2"

This converts

{%
include-markdown "../README.md"
start="<!-- why:start -->"
end="<!-- why:end -->"
%}

to

--8<-- "README.md:why"

KevinGimbel · 2026-01-20T10:11:00Z

I added prek and uv to mise so I could use them locally without installing the tools globally on my system.

In projects at work we use Hermit (https://github.com/cashapp/hermit) for tool management, but I think mise is quite similar to it.

Seems Zensical doesn't like symlinks, a snippet gets the same result

KevinGimbel · 2026-01-20T10:52:47Z

@j178 I had a quick look through the page side by side and it looks very good IMHO!

I opted to keep the snippets and includes from the README.md, but did not re-implement any hooks whatsoever.

For now, the config is still in yaml and called mkdocs.yml. Zensical will support this file for the foreseable future, and they plan to provide a migration command. Right now there's no real benefit of manually converting it to TOML.

I did not do any extra styling, the default theme looks clean and modern.

You can try this new build with mise run build-docs.

j178 · 2026-01-20T11:41:02Z

Yeah, the new style looks way better!

KevinGimbel added 2 commits January 20, 2026 10:12

chore: slight formatting adjustments

e6dbd55

feat: use zensical

2dbcc40

chore: add uv to mise.toml

66d97bc

KevinGimbel added 2 commits January 20, 2026 11:00

docs: update snippets and snippet markers for includes

52dad25

chore: add prek to mise.toml; run prek

c1cade1

KevinGimbel added 3 commits January 20, 2026 11:27

fix: use snippet for changelog instead of symlink

e8c4962

Seems Zensical doesn't like symlinks, a snippet gets the same result

chore: remove commented-out code

6c1f934

chore: remove commented-out code; run prek

8cc1f61

j178 merged commit 88c3c87 into j178:master Jan 20, 2026
22 checks passed

j178 changed the title ~~Draft: Move docs to zensical~~ Move docs to zensical Jan 20, 2026

BrewTestBot mentioned this pull request Jan 22, 2026

prek 0.3.0 Homebrew/homebrew-core#263954

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Move docs to zensical#1421

Move docs to zensical#1421
j178 merged 8 commits intoj178:masterfrom
AOEpeople:1176/move-docs-to-zensical

KevinGimbel commented Jan 20, 2026

Uh oh!

codecov bot commented Jan 20, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 20, 2026 •

edited

Loading

Head Branch Results

Base Branch Results

Uh oh!

KevinGimbel commented Jan 20, 2026 •

edited

Loading

Uh oh!

KevinGimbel commented Jan 20, 2026

Uh oh!

KevinGimbel commented Jan 20, 2026

Uh oh!

j178 commented Jan 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

KevinGimbel commented Jan 20, 2026

Uh oh!

codecov bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 Cargo Bloat Comparison

Head Branch Results

Base Branch Results

Uh oh!

KevinGimbel commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Snippets

Snipping markers

include markers

Uh oh!

KevinGimbel commented Jan 20, 2026

Uh oh!

KevinGimbel commented Jan 20, 2026

Uh oh!

j178 commented Jan 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov bot commented Jan 20, 2026 •

edited

Loading

github-actions bot commented Jan 20, 2026 •

edited

Loading

KevinGimbel commented Jan 20, 2026 •

edited

Loading