Restructure the README to the portfolio standard - #5
Open
adamXbot wants to merge 1 commit into
Open
Conversation
Reorders the README into the standard docs-repo shape: heading, status badge, disclosure block, where to read the docs, local commands, file layout, adding a page, and how it deploys. Corrections: - The one-line description said mantis is a "self-hostable mantis key service". It is a canary key service, per docs.json and index.mdx. - The deploy instructions told you to connect `privacykey/mantis-docs` in the Mintlify dashboard. That name only resolves as a rename redirect; the repository is `privacykey/docs-mantis`. - The README implied the docs site was a going concern. No docs domain for this project resolves, and no Mintlify GitHub App check appears on `main`, so the site is not live. The README now says so instead of pointing readers at a host that does not exist. - "The same checks run in GitHub Actions on pushes and pull requests" covered only two of the three workflows and omitted `npm run check`, the weekly external-link run and the daily changelog sync. All three workflows are now described with their real triggers. - The page index omitted `index.mdx`, `cli.md`, `cli-backup.md`, `changelog.mdx` and `deployment/index.mdx`, which are all in the docs.json navigation. They are listed now, grouped as the navigation groups them. Adds the frontmatter and navigation-registration rules enforced by scripts/check-docs.mjs, and the `just` shorthands from the justfile. No content was removed from the repository; the page annotations from the old link index are preserved in the file-layout section. README.md: 2998 -> 6324 bytes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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
1 participant
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.
Reshapes
README.mdinto the standard docs-repo order: H1, status badge, disclosure block,---, where to read the docs, run it locally, file layout, adding a page, how it deploys.Wrong facts removed
docs.json(description) andindex.mdx. Looks like a stray find-and-replace of "canary".privacykey/mantis-docsin the Mintlify dashboard" — that repository name only resolves as a GitHub rename redirect. The repository isprivacykey/docs-mantis, which is what the dashboard needs.main, so the site is not published. The README now states plainly that it is not live yet and points readers at the in-repo pages, rather than implying a host that does not exist.npm run validateandnpm run check-linksonly. It missednpm run check(scripts/check-docs.mjs), the weekly lychee external-link run, and the daily changelog sync. All three workflows are now listed with their actual triggers.Incomplete content fixed
The old page index omitted five pages that are in the
docs.jsonnavigation:index.mdx,cli.md,cli-backup.md,changelog.mdxanddeployment/index.mdx. The file-layout section now covers every navigation group and every page behind it, with the old annotations preserved.Also added: the frontmatter keys
scripts/check-docs.mjsactually enforces (titleanddescriptionrequired;iconandsidebarTitleallowed), the navigation-registration step, the link style the docs use (root-relative and extensionless in pages, relative only in the two.mintignored READMEs), and thejust run/just lintshorthands from thejustfile.Link verification
Every relative path in the new README was checked with
test -e, and every URL withcurl— all 30 relative links resolve to files that exist, and all four external URLs return 200.node scripts/check-docs.mjspasses.Size
README.md: 2998 -> 6324 bytes. Nothing was deleted from the repository; the old link index survives as the file-layout section, so no content needed moving to a new file.Note on the badge
The status badge currently renders "resource not found". The endpoint path is correct — it will resolve once the status hub PR on
privacykey/.githubmerges.Unrelated, not fixed here
The
Link checkworkflow is red onmainfor a reason outside this PR's scope:https://one.dash.cloudflare.com/indeployment/cloudflare.mdreturns 403 to lychee. It needs an--excludeor an--accept 403, in its own change.