cleanup: docs restructure and link/accessibility fixes#13
Merged
Conversation
…dation Delete 133 orphaned .mdx files not referenced in docs.json navigation (entire datzi/cli, web, plugins, providers dirs + scattered orphans), 15 stale READMEs, orphaned logos, llms.txt, AGENTS.md, docs/plans. Fix all 493 broken internal links in datzi pages (missing /datzi/ prefix, redirects for deleted pages, removed dead links). Strip 31 leaked H1 headings and 18 duplicate H1s from bulk-extracted datzi content. Restructure docs.json: nest qyl API groups, remove broken MEMORY ref, remove emoji from Datzi tab, merge single-page groups. Add scripts/validate-nav.mjs to catch ghost files and nav/file desync. Enhance pre-push hook to gate on broken links + a11y + nav sync. Harden CI to hard-fail on broken links and validate nav sync on PRs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR restructures docs by deleting obsolete/ghost pages, fixing broken links after a docs reorg, adding alt text to onboarding screenshots, and introducing pre-push validation with a navigation sync check.
Changes:
- Deleted ~80 obsolete doc files (CLI references, platform docs, provider pages, concept pages, READMEs) and removed duplicate headings
- Updated internal links across remaining docs to use
/datzi/prefix paths, converting dead links to either updated paths or plain text - Added pre-push hook, CI nav-sync validation step, and accessibility alt text on onboarding screenshots
Reviewed changes
Copilot reviewed 204 out of 206 changed files in this pull request and generated 12 comments.
Show a summary per file
| File | Description |
|---|---|
| package.json | Added lint:nav, validate, validate:quick scripts |
| .husky/pre-push | New pre-push hook running nav sync + link/a11y checks in parallel |
| .github/workflows/validate.yml | Added nav-sync CI step, removed continue-on-error from broken-links |
| logo/light.svg, logo/dark.svg | Deleted logo SVGs |
| datzi/start/onboarding.mdx | Added alt text to onboarding screenshots, fixed links |
| datzi/tools/skills.mdx | Fixed links (some now self-referencing) |
| datzi/gateway/remote.mdx | Fixed links (some now self-referencing) |
| datzi/gateway/troubleshooting.mdx | Fixed links (introduced duplicate entries) |
| datzi/install/index.mdx | Fixed links, removed Card hrefs |
| datzi/install/updating.mdx | Fixed links (introduced broken GitHub URL) |
| datzi/automation/hooks.mdx | Fixed links (introduced broken GitHub URL) |
| ~70 other files | Link prefix updates, duplicate heading removal, file deletions |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
|
|
||
| - `pnpm build` matters when you run the packaged `datzi` binary ([ | ||
| `datzi.mjs`](https://github.com/datzi/datzi/blob/main/datzi.mjs)) or use Node to run `dist/`. | ||
| `datzi.mjs`](https://github.com/datzi/blob/main/datzi.mjs)) or use Node to run `dist/`. |
| when the plugin is enabled and participate in the normal skill precedence rules. | ||
| You can gate them via `metadata.datzi.requires.config` on the plugin's config | ||
| entry. See [Plugins](/tools/plugin) for discovery/config and [Tools](/tools) for the | ||
| entry. See [Plugins](/datzi/tools/skills) for discovery/config and [Tools](/datzi/tools/index) for the |
| ## Config reference | ||
|
|
||
| See [Skills config](/tools/skills-config) for the full configuration schema. | ||
| See [Skills config](/datzi/tools/skills) for the full configuration schema. |
| - The app opens and manages the tunnel, so WebChat + health checks “just work.” | ||
|
|
||
| Runbook: [macOS remote access](/platforms/mac/remote). | ||
| Runbook: [macOS remote access](/datzi/gateway/remote). |
Comment on lines
+156
to
174
| <Card title="Docker" icon="container"> | ||
| Containerized or headless deployments. | ||
| </Card> | ||
|
|
||
| <Card title="Podman" href="/install/podman" icon="container"> | ||
| <Card title="Podman" icon="container"> | ||
| Rootless container: run `setup-podman.sh` once, then the launch script. | ||
| </Card> | ||
|
|
||
| <Card title="Nix" href="/install/nix" icon="snowflake"> | ||
| <Card title="Nix" icon="snowflake"> | ||
| Declarative install via Nix. | ||
| </Card> | ||
|
|
||
| <Card title="Ansible" href="/install/ansible" icon="server"> | ||
| <Card title="Ansible" icon="server"> | ||
| Automated fleet provisioning. | ||
| </Card> | ||
|
|
||
| <Card title="Bun" href="/install/bun" icon="zap"> | ||
| <Card title="Bun" icon="zap"> | ||
| CLI-only usage via the Bun runtime. | ||
| </Card> |
| - [Webhook Hooks](/automation/webhook) | ||
| - [Configuration](/gateway/configuration#hooks) | ||
| - CLI Reference: hooks | ||
| - [Bundled Hooks README](https://github.com/datzi/tree/main/src/hooks/bundled) |
Comment on lines
+246
to
+248
| - [/tools/browser](/datzi/tools/browser) | ||
| - [/tools/chrome-extension](/datzi/tools/browser) | ||
| - [/tools/browser](/datzi/tools/browser) |
| run: npm run lint:nav | ||
|
|
||
| - name: Check broken links | ||
| id: broken-links |
Comment on lines
+158
to
+159
| - [Exec tool](/datzi/tools/exec) | ||
| - [Exec](/datzi/tools/exec) |
| ## System requirements | ||
|
|
||
| - **[Node 22+](/install/node)** (the [installer script](#install-methods) will install it if missing) | ||
| - **[Node 22+](/datzi/install/index)** (the [installer script](#install-methods) will install it if missing) |
Summary of ChangesHello, I'm Gemini Code Assist1! 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 focuses on a significant cleanup and improvement of the project's documentation. The changes aim to enhance the user experience by ensuring accurate and accessible information, while also introducing automated checks to maintain documentation quality going forward. Highlights
Changelog
Ignored Files
Using Gemini Code AssistThe 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
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 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. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a significant restructuring of the documentation, including purging obsolete files and fixing broken links. A key addition is the pre-push validation hook, which will help maintain documentation quality by checking for broken links, accessibility issues, and navigation sync before code is pushed. The parallel execution of checks in the pre-push script is a nice touch for performance. I've also noticed the accessibility improvements by adding alt text to images, which is a great enhancement.
My review includes one suggestion for the new pre-push script to make it more robust by ensuring temporary files are cleaned up, even if the script is interrupted. Overall, this is a solid set of changes that improves the documentation's structure and maintainability.
| # Run mint checks in parallel using background jobs | ||
| echo "==> Running link and accessibility checks in parallel..." | ||
|
|
||
| tmpdir=$(mktemp -d) |
There was a problem hiding this comment.
This script creates a temporary directory but doesn't handle its cleanup if the script is interrupted (e.g., with Ctrl+C). This could leave temporary files on the system. It's also good practice to handle potential failures from mktemp.
I suggest adding a trap to ensure the temporary directory is always removed on script exit and to exit if mktemp fails.
Suggested change
| tmpdir=$(mktemp -d) | |
| tmpdir=$(mktemp -d) || { echo "Failed to create temporary directory" >&2; exit 1; } | |
| trap 'rm -rf -- "$tmpdir"' EXIT |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Includes commit 12bdc09 for the accessibility fix on onboarding screenshots.