feat(mdschema): add mdschema config to hk builtin config by hituzi-no-sippo · Pull Request #748 · jdx/hk

hituzi-no-sippo · 2026-03-18T13:40:01Z

Add mdschema as a new builtin linter for Markdown.

gemini-code-assist · 2026-03-18T13:44:42Z

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request adds mdschema, a schema-based Markdown validator, as a built-in linter. This addition aims to improve the quality and consistency of Markdown documentation by enforcing a defined structure and content requirements. The changes include the configuration of the linter, integration with the existing testing framework, and the addition of a tool stub for easy execution.

Highlights

New linter integration: This PR introduces mdschema as a new built-in linter for Markdown files, enhancing the validation and structure enforcement of Markdown documentation.
Configuration and testing: The PR includes a configuration file (mdschema.pkl) defining the linter's behavior and integrates tests to ensure its proper functioning.
Tool stub: A tool stub for mdschema is added to facilitate its execution within the development environment.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces support for mdschema as a new built-in linter for Markdown. The changes are well-structured, including the Pkl configuration with metadata, commands, tests, and a tool stub for version management. The implementation is solid. I have one suggestion to simplify the test data in pkl/builtins/mdschema.pkl to enhance test readability and maintainability.

gemini-code-assist · 2026-03-18T13:47:54Z

+    local const suffix =
+      """
+
+      ## Steps
+
+      ### Step 1: Install mdschema
+
+      Install mdschema using Go:
+
+      ```bash
+      go install github.com/jackchuka/mdschema/cmd/mdschema@latest
+      ```
+
+      ### Step 2: Create a Schema
+
+      Create a `.mdschema.yml` file:
+
+      ```yaml
+      structure:
+        - heading: "# My Project"
+          children:
+            - heading: "## Features"
+            - heading: "## Installation"
+      ```
+
+      ### Step 3: Validate a Markdown File
+
+      Run mdschema to validate your Markdown file:
+
+      ```bash
+      mdschema validate path/to/yourfile.md --schema path/to/.mdschema.yml
+      ```
+
+      ## Troubleshooting
+
+      If you encounter issues, check that Go is in your PATH.
+
+      ## Next Steps
+
+      Explore more advanced schema features in the documentation.
+      """


The test data for suffix is quite large as it's adapted from a tutorial. To improve the readability and maintainability of this test, consider simplifying the suffix to include only the minimal content required to satisfy the schema. This will make the test's intent clearer and less coupled to the example tutorial's content.

local const suffix = """ ## Steps ### Step 1: A step ```bash echo "A code block" ``` ## Troubleshooting This section is optional. ## Next Steps This section is also optional. """

https://github.com/jackchuka/mdschema mdschema is a schema-based Markdown documentation validator that validates Markdown files against YAML-defined schemas (.mdschema.yml). It supports checking headings, code blocks, images, tables, lists, links, word counts, and YAML frontmatter. This is a check-only tool with no fix/format capability. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

greptile-apps · 2026-04-01T10:55:37Z

Greptile Summary

This PR adds mdschema as a new builtin linter for the Markdown category, following the established pattern of the repository's other builtin configurations. The implementation is largely correct — metadata annotations, types filtering, test scaffold, and tool stub are all consistent with peer builtins.

Key findings:

Missing --schema {{workspace_indicator}} in the check command (P1): workspace_indicator = \".mdschema.yml\" is set, but check = \"mdschema check {{ files }}\" does not pass the resolved schema path to the tool. mdschema defaults to looking for .mdschema.yml in the working directory (repo root), so the step silently fails in any monorepo or sub-directory workspace where the schema lives in a subdirectory. Every other workspace-indicator-aware builtin (cargo_fmt, buf_lint, knip) explicitly references {{workspace_indicator}} or {{workspace}} in the command. The fix is mdschema check --schema {{workspace_indicator}} {{ files }}.
The test suite only exercises a single root-level .mdschema.yml sandbox, which masks the above bug — the test passes today regardless.

Confidence Score: 4/5

Safe to merge after fixing the missing --schema flag in the check command; the bug only manifests in monorepo setups but is easy to address

One P1 defect: the check command omits --schema {{workspace_indicator}}, causing silent failures when .mdschema.yml is in a subdirectory workspace. The fix is a one-line change. All other aspects of the PR (tool stub, metadata, test structure, schema content) are correct.

pkl/builtins/mdschema.pkl — specifically line 17, the check command

Important Files Changed

Filename	Overview
pkl/builtins/mdschema.pkl	New mdschema builtin step; uses workspace_indicator but check command omits --schema {{workspace_indicator}}, breaking monorepo/sub-directory workspace scenarios
test/builtin_tool_stubs/mdschema	Tool stub correctly pins mdschema at v0.12.8 via aqua; follows the same pattern as all other stubs in the directory

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Git pre-commit hook] --> B{Any staged .md files?}
    B -- No --> C[Step skipped]
    B -- Yes --> D{workspace_indicator
.mdschema.yml found?}
    D -- No --> C
    D -- Yes --> E[Group files by workspace]
    E --> F["Run: mdschema check {{ files }}
(current PR — no --schema flag)"]
    F --> G{mdschema finds
.mdschema.yml in CWD?}
    G -- "Yes (schema at repo root)" --> H[Validation runs correctly]
    G -- "No (schema in subdirectory)" --> I[Error: schema not found]
    H --> J{Validation passes?}
    J -- Yes --> K[Exit 0 ✅]
    J -- No --> L[Exit 1 ❌ lint failure]

    style I fill:#f88,stroke:#c00
    style F fill:#ffd,stroke:#aa0

_{Reviews (1): Last reviewed commit: "feat(mdschema): add mdschema config to h..." | Re-trigger Greptile}

greptile-apps · 2026-04-01T10:55:40Z

+  types = List("markdown")
+  check = "mdschema check {{ files }}"
+  tests {
+    local const requiredText = "install"


check command ignores workspace_indicator schema path

workspace_indicator = ".mdschema.yml" tells hk to group files by their nearest workspace directory containing .mdschema.yml, but the check command does not pass that schema path to the tool. mdschema check {{ files }} runs from the repo root, so mdschema will look for .mdschema.yml in the CWD. This works when the schema lives at the repo root, but silently fails (tool can't find the schema) in any monorepo or sub-directory workspace.

Every other builtin that uses workspace_indicator passes the resolved path explicitly:

cargo_fmt → cargo fmt --manifest-path {{workspace_indicator}}

buf_lint → buf lint {{workspace}}

knip → knip --no-progress --directory {{workspace}}

The fix is to use the --schema flag mdschema provides:

Suggested change

local const requiredText = "install"

check = "mdschema check --schema {{workspace_indicator}} {{ files }}"

The tests pass today only because the test sandbox places .mdschema.yml in the tmpdir root (i.e. the CWD), masking the bug for the monorepo path.

@hituzi-no-sippo

### 🚀 Features - **(betterleaks)** add betterleaks config to hk builtin config by [@hituzi-no-sippo](https://github.com/hituzi-no-sippo) in [#750](#750) - **(builtins)** add google-java-format to builtins by [@timothysparg](https://github.com/timothysparg) in [#777](#777) - **(builtins)** add dclint to builtins by [@timothysparg](https://github.com/timothysparg) in [#779](#779) - **(config)** set default value for exclude to List() by [@timothysparg](https://github.com/timothysparg) in [#781](#781) - **(core)** add required field to prevent unconfigured steps from running by [@timothysparg](https://github.com/timothysparg) in [#785](#785) - **(gitleaks)** add gitleaks config to hk builtin config by [@hituzi-no-sippo](https://github.com/hituzi-no-sippo) in [#749](#749) - **(mdschema)** add mdschema config to hk builtin config by [@hituzi-no-sippo](https://github.com/hituzi-no-sippo) in [#748](#748) - **(pkl)** add pklr as opt-in pkl backend by [@jdx](https://github.com/jdx) in [#769](#769) - add pklr as opt-in pkl backend by [@jdx](https://github.com/jdx) in [#768](#768) ### 🐛 Bug Fixes - **(docs)** replace invalid /latest/ pkl package URIs with versioned format by [@jdx](https://github.com/jdx) in [#770](#770) - **(stage)** do not stage pre-existing untracked files by [@jdx](https://github.com/jdx) in [#788](#788) ### 📚 Documentation - add benchmarks page and reproducible benchmark suite by [@jdx](https://github.com/jdx) in [#766](#766) - add recommended setup section to mise integration by [@timothysparg](https://github.com/timothysparg) in [#780](#780) ### 📦️ Dependency Updates - lock file maintenance by [@renovate[bot]](https://github.com/renovate[bot]) in [#762](#762) - update rust crate pklr to 0.4 by [@renovate[bot]](https://github.com/renovate[bot]) in [#776](#776) - update apple-actions/import-codesign-certs digest to fe74d46 by [@renovate[bot]](https://github.com/renovate[bot]) in [#774](#774) - update anthropics/claude-code-action digest to 094bd24 by [@renovate[bot]](https://github.com/renovate[bot]) in [#773](#773) - update taiki-e/upload-rust-binary-action digest to 0e34102 by [@renovate[bot]](https://github.com/renovate[bot]) in [#775](#775) - bump usage to 3.2.0 and pkl to 0.31.1, add windows platforms by [@jdx](https://github.com/jdx) in [#787](#787) - lock file maintenance by [@renovate[bot]](https://github.com/renovate[bot]) in [#786](#786) ### New Contributors - @timothysparg made their first contribution in [#781](#781)  --- > [!NOTE] > **Medium Risk** > Primarily a version/documentation bump, but it also updates the Rust dependency lockfile (e.g., `hyper` and `windows-sys`), which could introduce build/runtime regressions. > > **Overview** > Bumps hk to **v1.40.0** and publishes the corresponding release notes in `CHANGELOG.md`. > > Updates generated CLI/docs and all Pkl package URL references in docs/examples to point at `v1.40.0`, and refreshes `Cargo.lock` with dependency updates/removals consistent with the new release. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit da00ab8. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup>  Co-authored-by: mise-en-dev <123107610+mise-en-dev@users.noreply.github.com>

This MR contains the following updates: | Package | Update | Change | |---|---|---| | [hk](https://github.com/jdx/hk) | minor | `1.39.0` → `1.40.0` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>jdx/hk (hk)</summary> ### [`v1.40.0`](https://github.com/jdx/hk/blob/HEAD/CHANGELOG.md#1400---2026-04-01) [Compare Source](jdx/hk@v1.39.0...v1.40.0) ##### 🚀 Features - **(betterleaks)** add betterleaks config to hk builtin config by [@hituzi-no-sippo](https://github.com/hituzi-no-sippo) in [#750](jdx/hk#750) - **(builtins)** add google-java-format to builtins by [@timothysparg](https://github.com/timothysparg) in [#777](jdx/hk#777) - **(builtins)** add dclint to builtins by [@timothysparg](https://github.com/timothysparg) in [#779](jdx/hk#779) - **(config)** set default value for exclude to List() by [@timothysparg](https://github.com/timothysparg) in [#781](jdx/hk#781) - **(core)** add required field to prevent unconfigured steps from running by [@timothysparg](https://github.com/timothysparg) in [#785](jdx/hk#785) - **(gitleaks)** add gitleaks config to hk builtin config by [@hituzi-no-sippo](https://github.com/hituzi-no-sippo) in [#749](jdx/hk#749) - **(mdschema)** add mdschema config to hk builtin config by [@hituzi-no-sippo](https://github.com/hituzi-no-sippo) in [#748](jdx/hk#748) - **(pkl)** add pklr as opt-in pkl backend by [@jdx](https://github.com/jdx) in [#769](jdx/hk#769) - add pklr as opt-in pkl backend by [@jdx](https://github.com/jdx) in [#768](jdx/hk#768) ##### 🐛 Bug Fixes - **(docs)** replace invalid /latest/ pkl package URIs with versioned format by [@jdx](https://github.com/jdx) in [#770](jdx/hk#770) - **(stage)** do not stage pre-existing untracked files by [@jdx](https://github.com/jdx) in [#788](jdx/hk#788) ##### 📚 Documentation - add benchmarks page and reproducible benchmark suite by [@jdx](https://github.com/jdx) in [#766](jdx/hk#766) - add recommended setup section to mise integration by [@timothysparg](https://github.com/timothysparg) in [#780](jdx/hk#780) ##### 📦️ Dependency Updates - lock file maintenance by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#762](jdx/hk#762) - update rust crate pklr to 0.4 by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#776](jdx/hk#776) - update apple-actions/import-codesign-certs digest to [`fe74d46`](jdx/hk@fe74d46) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#774](jdx/hk#774) - update anthropics/claude-code-action digest to [`094bd24`](jdx/hk@094bd24) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#773](jdx/hk#773) - update taiki-e/upload-rust-binary-action digest to [`0e34102`](jdx/hk@0e34102) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#775](jdx/hk#775) - bump usage to 3.2.0 and pkl to 0.31.1, add windows platforms by [@jdx](https://github.com/jdx) in [#787](jdx/hk#787) - lock file maintenance by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#786](jdx/hk#786) ##### New Contributors - [@timothysparg](https://github.com/timothysparg) made their first contribution in [#781](jdx/hk#781) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

gemini-code-assist Bot reviewed Mar 18, 2026

View reviewed changes

hituzi-no-sippo force-pushed the feat/add-mdschema-to-builtin branch from 964a2de to 857f88e Compare April 1, 2026 01:01

hituzi-no-sippo marked this pull request as ready for review April 1, 2026 10:51

greptile-apps Bot reviewed Apr 1, 2026

View reviewed changes

jdx merged commit 191ea4d into jdx:main Apr 1, 2026
20 checks passed

jdx mentioned this pull request Apr 1, 2026

chore: release v1.40.0 #763

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(mdschema): add mdschema config to hk builtin config#748

feat(mdschema): add mdschema config to hk builtin config#748
jdx merged 1 commit intojdx:mainfrom
hituzi-no-sippo:feat/add-mdschema-to-builtin

hituzi-no-sippo commented Mar 18, 2026

Uh oh!

gemini-code-assist Bot commented Mar 18, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Mar 18, 2026

Uh oh!

greptile-apps Bot commented Apr 1, 2026

Uh oh!

greptile-apps Bot Apr 1, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	local const requiredText = "install"
	check = "mdschema check --schema {{workspace_indicator}} {{ files }}"

Uh oh!

Conversation

hituzi-no-sippo commented Mar 18, 2026

Uh oh!

gemini-code-assist Bot commented Mar 18, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot commented Apr 1, 2026

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Flowchart

Uh oh!

greptile-apps Bot Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants