Skip to content

[WIP] add Mintlify docs verification workflow#778

Draft
Blargian wants to merge 2 commits into
ClickHouse:mainfrom
Blargian:docs-verify-mintlify
Draft

[WIP] add Mintlify docs verification workflow#778
Blargian wants to merge 2 commits into
ClickHouse:mainfrom
Blargian:docs-verify-mintlify

Conversation

@Blargian

@Blargian Blargian commented Jun 4, 2026

Copy link
Copy Markdown
Member

Summary

Verify this repo's docs/ as a slice of the aggregated ClickHouse docs site over on ClickHouse/ClickHouse. The job runs inside the clickhouse/docs-builder image, where git, python3 and mint (mintlify CLI) are all present, so nothing is installed and this repo vendors no scripts.

It fetches the check driver from ClickHouse/ClickHouse at runtime; the driver shallow/sparse-clones the aggregator docs and any scripts needed to run the docs check, replaces the language client docs copy in the aggregator repo with this repo's docs/ (from the branch the docs check runs on) and runs the same checks that ClickHouse/ClickHouse docs check runs from the docs root. A non-zero exit fails the job.

Requires:

  1. CI (docs): Reusable Mintlify docs checks for integrations repos ClickHouse#106258 (refactors the Mintlify docs check as part of praktika to be easily consumable from other repos without needing praktika as a dependency)
  2. PR to add the Mintlify site in https://github.com/ClickHouse/mintlify-docs-dev to the server repo.

Checklist

Delete items not relevant to your PR:

  • Unit and integration tests covering the common scenarios were added
  • A human-readable description of the changes was provided to include in CHANGELOG
  • For significant changes, documentation in https://github.com/ClickHouse/clickhouse-docs was updated with further explanations or tutorials

Verify this repo's docs/ as a slice of the aggregated ClickHouse docs site.
The job runs inside the clickhouse/docs-builder image, where git, python3 and
mint are all present, so nothing is installed and this repo vendors no scripts.

It fetches the check driver from ClickHouse/ClickHouse at runtime; the driver
shallow/sparse-clones the aggregator docs (bringing ci/jobs/scripts/docs along
for free), replaces the Python client folder with this repo's docs/ -- wiping
it first so deletions and renames are reflected -- and runs the checks
(mint validate + mint broken-links) from the docs root. A non-zero exit fails
the job, so a green run means every check passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Changes to the workflow itself should also run the check, so add the
workflow file to the paths filter of both triggers.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
image: clickhouse/docs-builder
steps:
- name: Checkout clickhouse-connect
uses: actions/checkout@v4

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'll need to update this to v5

Suggested change
uses: actions/checkout@v4
uses: actions/checkout@v5

@joe-clickhouse

joe-clickhouse commented Jun 10, 2026

Copy link
Copy Markdown
Contributor

According to Claude:

Status update after ClickHouse/ClickHouse#106258 merged today. I re-ran the failed Mintlify check and the workflow itself now works end to end. The driver downloads, splices this repo's docs into the aggregator, and runs both checks.

The remaining failures are not problems with this workflow.

  1. The aggregator docs on ClickHouse master are still a skeleton. The missing snippet and most of the broken links are pages that exist in mintlify-docs-dev but have not been imported to the server repo yet. The check cannot pass until that lands.
  2. Our docs still used the old /core link prefix, which does not exist in the new site layout. Fix is up in fix docs links for the new Mintlify site layout #794. Once that merges, a re-run here will pick it up through the merge ref.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants