docs: make Kanvas and Layer5 Cloud page language end-user facing - #1227
docs: make Kanvas and Layer5 Cloud page language end-user facing#1227ritzorama wants to merge 2 commits into
Conversation
A language and examples pass over the pages published by #1223-#1226. Reader-facing wording only; no page was restructured and no heading anchor changed. - kanvas/reference/keyboard-shortcuts: drop 207 lines of Hugo theme demo boilerplate (Go/Chroma sample, lorem ipsum, Godzilla definition list, theme-test prose). It sat in an HTML comment, so it was invisible on the page but still shipped in the page source. Removes 28 markdownlint violations. - kanvas/designer/export-designs: answer the "can I export an earlier version?" question in terms of what the reader can do, not in terms of export endpoints. - kanvas/designer/configuring-components: "schema" -> "definition" in prose. The Json Schema tab keeps its name, because that is what the UI calls it. - cloud/academy/building-challenges: "not a fixed schema" -> "not a fixed structure". - cloud/academy/building-certifications: UUID -> ID in prose. Literal <your-organization-uuid> / <your-certification-uuid> placeholders are unchanged, since authors copy those verbatim. The renamed heading pins its original anchor. - AGENTS.md: record how to rename a heading without breaking its anchor, and how to verify it. Signed-off-by: miacycle <184569369+miacycle@users.noreply.github.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (1)
Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review. 📝 WalkthroughWalkthroughDocumentation updates clarify identifiers, section conventions, component definitions, export behavior, and Kanvas keyboard shortcuts. AGENTS.md documents a Goldmark escape issue for literal backslashes in inline HTML. ChangesDocumentation updates
Estimated code review effort: 2 (Simple) | ~10 minutes Merge Risk: ⚪ Minimal · up to This change improves end-user wording, removes shipped theme boilerplate, and corrects documented keyboard shortcuts while preserving page coverage and anchors. No actionable merge-blocking risk remains after normal checks and review. Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Full details: Docstring CoverageExplanation No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (2 skipped: 2 unsupported.) ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
This PR refines the tone and vocabulary of several Kanvas and Layer5 Cloud documentation pages to be more end-user oriented, and removes hidden Docsy/Hugo theme demo boilerplate that was being shipped in the HTML source of a Kanvas reference page. It also captures the heading-anchor preservation technique in AGENTS.md for future doc edits.
Changes:
- Removed a large block of commented-out theme demo content from the Kanvas keyboard shortcuts reference page.
- Reworded a handful of passages to avoid implementation-centric terms (e.g., “endpoint”, “schema”, “UUID”) while preserving UI labels and anchors.
- Added durable guidance to
AGENTS.mdon preserving heading anchors when renaming headings.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| content/en/kanvas/reference/keyboard-shortcuts.md | Removes hidden theme demo boilerplate so the shipped HTML matches the actual user-facing reference content. |
| content/en/kanvas/designer/export-designs/index.md | Rephrases the “export earlier version” FAQ answer in user-centric terms while keeping the same behavior. |
| content/en/kanvas/designer/configuring-components/index.md | Replaces “schema”-centric wording with “definition”/field-focused wording while keeping the “Json Schema” UI label. |
| content/en/cloud/academy/creating-content/building-challenges/index.md | Rewords “not a fixed schema” to “not a fixed structure” for clearer author guidance. |
| content/en/cloud/academy/creating-content/building-certifications/index.md | Softens UUID-centric wording to “ID”, preserves the original anchor via {#...}, and adjusts related copy accordingly. |
| AGENTS.md | Documents the heading-anchor preservation technique and a verification approach for ensuring anchors aren’t lost. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
🚀 Preview deployment: https://docs.layer5.io/pr-preview/pr-1227/
|
Nine shortcuts bound in hotkeys.ts were missing from the page; seven of them
are shown in the in-app shortcuts dialog, so a user could see them in Kanvas
and then fail to find them in the documentation. Ctrl/Cmd+E (pen mode) and I
(image picker) were undocumented everywhere.
Added to the Designer section: I, Ctrl+P, Ctrl+E, H, Space, V, \, Ctrl+/ and
Ctrl+Shift+/.
Corrected claims that nothing implements:
- Ctrl+Shift++ / Ctrl+Shift+- ("Zoom in/out on the Page") are not bound in
hotkeys.ts. Replaced with a note that page zoom is the browser's, not Kanvas's.
- The Operator section's Ctrl+` (open terminal), / (search) and ` (close
terminal) are bound nowhere in meshery-extensions. The terminal is opened
from the pod's terminal badge or the Details panel's Terminal tab, and is
closed with Esc (customTerminal keyCode 27). Replaced accordingly, with a
link to Interactive Terminal.
- Esc now describes what it does - leave the current mode, return to selection
mode - alongside closing menus and dialogs.
No heading was renamed. A full Hugo build of master and this branch produces an
identical set of 5,926 heading id= anchors.
Signed-off-by: miacycle <184569369+miacycle@users.noreply.github.com>
A language and examples pass over the 33 pages published by #1223, #1224, #1225 and #1226.
The pages were written from the implementation and are accurate; what was in question was
whether they read as documentation for someone using the product. Five pages needed a
change. The other 28 were read and left alone.
The confirmed defect
content/en/kanvas/reference/keyboard-shortcuts.mdcarried 207 lines of Hugo theme demoboilerplate: a Go/Chroma syntax-highlighting sample, lorem ipsum, a Godzilla definition list,
a Beastie Boys table, and literal theme-test prose ("Long, single-line code blocks should not
wrap...").
One correction to the brief's framing. It was not visible on the rendered page - it sat
inside an HTML comment opened at line 68 and closed at line 267. It was still shipped: Hugo
passes the raw comment straight through, so every request for that page carried ~9 KB of dead
theme text in the HTML source. Invisible, but wrong to leave in a user reference page. Removed
in full; the three real sections and their anchors are untouched. Side effect: 28 fewer
markdownlint violations on that file (108 -> 80).
Vocabulary
Each item from the review, and what was done with it.
endpointendpointschemaschemaUUID<your-organization-uuid>and<your-certification-uuid>placeholders are unchanged - authors copy those verbatim into directory paths and front matter, so changing them would break the instructions.MeshSync"CRUD operations"
Checked, as asked. The flagged language does not survive anywhere in these pages.
cloud/concepts/identity-and-security/keys.mdalready spells the four key types out in plainEnglish ("the action they grant is not simply creating, reading, updating or deleting
something"). The only
CRUDleft in the repo is in two release-notes pages, which quote PRtitles verbatim and are out of scope. No change needed.
Examples
Read against the
cloud/concepts/spaces/environments.mdbar (Orbital Labs, named people, EKS/ RDS / S3 / CloudFront / SQS). The rest hold up:
roles/_index.mdruns the same Orbital Labsscenario,
performance-testingseedsService - checkout,managing-workspacestalks aboutstaging and production. No example was found showing internal identifiers, function names, or
a scenario only a contributor would be in. Nothing changed here.
Considered and left:
cloud/concepts/catalog/_index.md:91explains a failed URL import interms of
400/500/502. It reads engineering-ish, but it is troubleshooting for anerror the importer surfaces, and rewriting it was outside a language pass. Flagging it rather
than silently changing it.
Anchors - the hard requirement
One heading was renamed:
### Find Your Organization UUID and Certification ID->### Find Your Organization ID and Certification ID. Its original anchor is pinned with{#find-your-organization-uuid-and-certification-id}, so any spreadsheet row pointing at itstill resolves.
Verified mechanically rather than by eye. Built master and this branch to separate directories
and diffed the
id=attribute of every<h1>-<h6>in all 1,631 generated pages:Both builds are clean, all 127 aliases still emit, and
markdownlint-cli2reports no newviolations on any changed file.
Also in this PR
AGENTS.mdgains a short note under "Keeping old URLs alive" on renaming a heading withoutbreaking its anchor (
{#old-slug}) and on the build-and-diff check used above, so the nextperson does not have to rediscover it.
Follow-up: keyboard shortcut coverage (second commit)
While that page was open, its shortcut lists were compared against the bindings in
meshery-extensions/ui/src/modules/editor/modes/designer/hotkeys.tsand against the in-appdialog (
components/common/Dialog/Help/Shortcuts.tsx, opened with Ctrl/Cmd +/). The page was both incomplete and, in five places, wrong.
Nine bound shortcuts were missing
Seven of them are already listed in the in-app dialog, so a user could see them in Kanvas and
then fail to find them here. Two are bound but shown nowhere at all.
Five documented shortcuts that nothing implements
Page".
hotkeys.tsbindsctrl+=andctrl+-for canvas zoom and has noctrl+shift+=or
ctrl+shift+-binding at all. Page zoom is the browser's, not Kanvas's. Both bullets arereplaced by one sentence saying so, rather than naming a key combination this repo cannot
verify across browsers.
</kbd> (open terminal), <kbd>/</kbd> (search) and <kbd>(close terminal). None of the three is bound anywhere inmeshery-extensions:hotkeys.tsis the only place the UI registers hotkeys, and a repo-widesearch for
keydown/keyup/onKeyDown/event.keyturns up nothing else that couldbind them. What is real: the terminal opens from the pod's terminal badge
(
modules/editor/comman/badges.ts) or the Details panel's Terminal tab, and closes onEsc (
components/customTerminal/index.tsx,keyCode === 27). The section nowsays that and links to Interactive Terminal.
Esc in the Designer list also gained what it actually does - leave the current mode
and return to selection mode - alongside the "closes menus and dialogs" it already claimed.
Two things for someone else, deliberately not changed here
of the product say Operator. The docs are right; the rename belongs in
meshery-extensions, not in this PR.hotkeys.tsdeclares 46 hotkey strings but binds only 37.ctrl+x/command+x- cut -is among the nine that are declared and never bound, so copy and paste work and cut silently
does nothing. None of the nine is documented here, and none should be until they are wired up.
Anchors
No heading was renamed by this commit either. Rebuilt master and this branch and diffed the
id=attribute of every<h1>-<h6>across all 1,631 generated pages: 5,926 anchors on bothsides, zero lost, zero added.
One Goldmark trap worth knowing, now recorded in
AGENTS.md: writing the backslash key as<button ...>\</button>makes Goldmark read\<as an escaped<, and the tag never closes -the page renders a literal
</button>. It has to be\, and the check is the built HTML,not the source.
Summary by CodeRabbit