docs: replace hardcoded Related Docs with Related Reading - #1129
docs: replace hardcoded Related Docs with Related Reading#1129nafisa404 wants to merge 4 commits into
Conversation
![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 adds the "Dock" tag to the "Understanding Tool Modes" documentation page and removes a related documentation link from the "Pinning Models to Dock" page. The reviewer suggested using lowercase for the "dock" tag to maintain casing consistency and questioned the semantic relevance of adding this tag to the tool modes page.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
|
Preview deployment for PR #1129 removed. This PR preview was automatically pruned because we keep only the 6 most recently updated previews on GitHub Pages to stay within deployment size limits. If needed, push a new commit to this PR to generate a fresh preview. |
Signed-off-by: Nafisa Tahasin <nafisatahasin23@gmail.com>
278c6e9 to
d660d24
Compare
|
The scope of the replacement is a bigger one. Take a look at the following example: meshery/meshery#20150 You have to make sure that all of the hardcoded "See also", "Related reading", "Related Suggestions", etc are removed from the repo. So, just how you went and removed this one and added a topic to the categories/tags within the frontmatter, you have to do so in all of the removed hardcoded instances to make sure that the related reading suggestions are not lost. |
|
@nafisa404 Keep me updated if you need any help |
… before related-reading migration
…candidates related-reading.html used .Site.RegularPages.Related, but Hugo's RegularPages structurally excludes every _index.md (section) page. This meant a section landing page (e.g. kanvas/operator/_index.md) could never appear in another page's Related Reading, no matter how its tags/categories lined up. Widen the candidate pool to Pages filtered to Kind in [page, section] before calling .Related. Verified with a before/after build diff across the whole site (dumped Related Reading links for all 1519/1523 pages, before vs after): zero pages lost their Related Reading section, 2 previously-invisible relationships now correctly surface, and the ~66 pages whose list composition shifted did so only because section pages joined the eligible pool, not because of any lost or broken links. Signed-off-by: Nafisa Tahasin <nafisatahasin23@gmail.com>
Repo-wide follow-up to PR layer5io#1129 (issue layer5io#1028), applying the same pattern used for Pinning Models to the Dock / Understanding Tool Modes across the rest of the docs: remove hardcoded "Related Docs"/"See Also"/"Related pages"/"Related" link blocks and inline references, and let the site's taxonomy-driven Related Reading partial surface the same connections via categories/tags instead. Migrated: - videos/getting-started/basics/operator-overview.md (-> kanvas/operator/_index.md) - videos/getting-started/basics/designer-overview.md (-> kanvas/designer/_index.md) - videos/getting-started/comments/design-reviews-full.md (-> kanvas/designer/comments/index.md) - kanvas/operator/log-streaming/index.md <-> interactive-terminal/index.md, advanced/performance/index.md - kanvas/operator/interactive-terminal/index.md <-> log-streaming/index.md - kanvas/advanced/render-modes.md <-> autopan.md, performance/index.md, url-parameters/index.md - kanvas/advanced/autopan.md <-> render-modes.md, performance/index.md, url-parameters/index.md - kanvas/advanced/performance/index.md <-> render-modes.md, autopan.md - cloud/guides/organizations/configuration-scenarios/index.md <-> white-labeling, identity-services, organizations (concept), identity-and-security Front matter changes, only where existing categories/tags didn't already establish the connection: - log-streaming + interactive-terminal: added tags: [troubleshooting] (shared category Operator alone is a 7-way tie that doesn't reliably survive the top-6 cutoff) - operator-overview.md + kanvas/operator/_index.md: added tags: [operator-overview] - designer-overview.md + kanvas/designer/_index.md: added tags: [designer-overview] (uncommented/set; was previously commented out) - configuration-scenarios.md, white-labeling/_index.md, identity-services/index.md, identity-and-security/_index.md: added the existing "orgs" tag where missing, so each shares 2-3 tags with configuration-scenarios rather than relying on the generic Identity category alone (13 pages deep, easily crowded out of the top 6) Depends on the related-reading.html section-page fix in the preceding commit for 5 of these links (kanvas/operator/_index.md, kanvas/designer/_index.md, white-labeling/_index.md, organizations/_index.md, identity-and-security/_index.md are all section pages). Verified: hugo build (1523 pages, no errors) and manual inspection of rendered Related Reading output on every migrated page. Signed-off-by: Nafisa Tahasin <nafisatahasin23@gmail.com>
Repo-wide follow-up to PR layer5io#1129 (issue layer5io#1028), applying the same pattern used for Pinning Models to the Dock / Understanding Tool Modes across the rest of the docs: remove hardcoded "Related Docs"/"See Also"/"Related pages"/"Related" link blocks and inline references, and let the site's taxonomy-driven Related Reading partial surface the same connections via categories/tags instead. Migrated: - videos/getting-started/basics/operator-overview.md (-> kanvas/operator/_index.md) - videos/getting-started/basics/designer-overview.md (-> kanvas/designer/_index.md) - videos/getting-started/comments/design-reviews-full.md (-> kanvas/designer/comments/index.md) - kanvas/operator/log-streaming/index.md <-> interactive-terminal/index.md, advanced/performance/index.md - kanvas/operator/interactive-terminal/index.md <-> log-streaming/index.md - kanvas/advanced/render-modes.md <-> autopan.md, performance/index.md, url-parameters/index.md - kanvas/advanced/autopan.md <-> render-modes.md, performance/index.md, url-parameters/index.md - kanvas/advanced/performance/index.md <-> render-modes.md, autopan.md - cloud/guides/organizations/configuration-scenarios/index.md <-> white-labeling, identity-services, organizations (concept), identity-and-security Front matter changes, only where existing categories/tags didn't already establish the connection: - log-streaming + interactive-terminal: added tags: [troubleshooting] (shared category Operator alone is a 7-way tie that doesn't reliably survive the top-6 cutoff) - operator-overview.md + kanvas/operator/_index.md: added tags: [operator-overview] - designer-overview.md + kanvas/designer/_index.md: added tags: [designer-overview] (uncommented/set; was previously commented out) - configuration-scenarios.md, white-labeling/_index.md, identity-services/index.md, identity-and-security/_index.md: added the existing "orgs" tag where missing, so each shares 2-3 tags with configuration-scenarios rather than relying on the generic Identity category alone (13 pages deep, easily crowded out of the top 6) Depends on the related-reading.html section-page fix in the preceding commit for 5 of these links (kanvas/operator/_index.md, kanvas/designer/_index.md, white-labeling/_index.md, organizations/_index.md, identity-and-security/_index.md are all section pages). Verified: hugo build (1523 pages, no errors) and manual inspection of rendered Related Reading output on every migrated page. Signed-off-by: Nafisa Tahasin <nafisatahasin23@gmail.com>
4eead33 to
781fce3
Compare
|
@banana-three-join Implemented the requested changes by removing the remaining hardcoded Related Docs, See Also, and similar sections across the docs and migrating those relationships to the frontmatter using tags/categories for the automatic Related Reading system. |
hiyach28
left a comment
hiyach28
left a comment
There was a problem hiding this comment.
Built the docs site locally and verified the generated HTML.
Everything works exactly as intended:
layouts/partials/related-reading.html safely handles the inclusion of _index.md files without breaking any template loops.
The new tags successfully wire up the expected relationships (e.g., Navigating Operator and Reviewing Designs now correctly surface in the Related Reading blocks of the respective video pages).
LGTM! @banana-three-join i think its ready to merge, please review
|
@banana-three-join this has been stale for a while...would you please review it when you have a moment..Thanks. |
banana-three-join
left a comment
banana-three-join
left a comment
There was a problem hiding this comment.
Cleanup looks good - thanks for the reminder to re-review. As far as I can tell all of the hand-written "Related Reading" sections have been removed.
Beyond the per-file comments, three things I'd like addressed before merge:
1. The related-reading partial changes behavior and isn't called out anywhere
Switching from .Site.RegularPages to where .Site.Pages "Kind" "in" (slice "page" "section") widens the candidate set: section landing pages (_index.md) can now be returned as related results. Our _index.md files carry real tags/categories, so this isn't theoretical - they will surface.
Combined with the current [related] config it's more pronounced than it looks:
threshold = 1means any single term match qualifies, so there's effectively no relevance filtering.categoriesis weighted 200 vstagsat 100, and section indexes tend to carry broad categories. They'll frequently outrank actual articles.
The term counts below make the practical effect clear: categories: [Designer] is on 38 pages. Every one of those matches every other at score 200, so with first 6 the list is close to arbitrary within the category. If we're keeping section pages as candidates, hugo.toml should be adjusted in this PR too - at minimum lowering categories below tags, and probably raising threshold. If including section pages wasn't intentional, .Site.RegularPages.Related . gives the previous behavior with no filter needed.
2. The issue/PR description needs updating to reflect what the PR actually does now.
3. Tags and categories need normalizing
Full inventory from grep -rhoP '^(tags|categories):.*' content/ | sort | uniq -c | sort -rn is below. The issues:
- Casing -
[tutorials](13) vs[Tutorials](5), plusDesigner,Identity,Security,Academy,Dock,Pin,Models. Hugo normalizes the term key so these do merge, but the rendered display title comes from whichever it sees first, so the taxonomy pages end up inconsistent. Lowercase everything. - Scalar instead of list -
categories: "platform"andcategories: "cloud"are strings, not sequences. Should be[platform]/[cloud]. - Duplicate concept across both taxonomies - e.g.
categories: [Identity, Security]withtags: [permissions, identity, ...]on the same page. Because the two indices are scored independently, that single concept contributes 300 instead of 200. Worth deciding whether a term belongs in one taxonomy or the other. - Compound tags -
designer-overview,operator-overview. These never matchdesigneroroperator, so they fragment the index for no benefit. Suggest splitting. - Synonyms -
permsvspermissions.
Full term counts
38 categories: [Designer] 18 tags: [designs] 13 categories: [tutorials] 12 categories: [Identity] 10 categories: [Self-Hosted] 10 categories: [Security] 10 categories: [Academy] 9 tags: [Academy] 6 categories: [Operator] 5 tags: [users] 5 categories: [Tutorials] 5 categories: [Spaces] 5 categories: [Reference] 4 tags: [Designer] 4 categories: [Catalog] 3 tags: [review, collaboration, comments] 3 tags: [orgs] 3 tags: [extensibility] 3 categories: [Designer, Tutorials] 3 categories: [Designer, Operator] 2 tags: [troubleshooting] 2 tags: [performance] 2 tags: [meshery] 2 tags: [docs] 2 categories: [Workspaces] 2 categories: [kanvas] 2 categories: [About] 1 tags: [workspaces, sharing, designs] 1 tags: [workspaces, roles] 1 tags: [white-labeling, custom-domain, orgs] 1 tags: [user, roles] 1 tags: [teams, roles] 1 tags: [teams] 1 tags: [sessions, permissions] 1 tags: [roles, permissions] 1 tags: [perms] 1 tags: [permissions, identity, authentication, orgs] 1 tags: [permissions] 1 tags: [performance, rendering] 1 tags: [performance, interaction] 1 tags: [orgs, roles] 1 tags: [orgs, custom-domain, identity, byoc, white-labeling] 1 tags: [operator-overview] 1 tags: [monitoring] 1 tags: [layer5, cloud, infrastructure] 1 tags: [kubernetes, infrastructure] 1 tags: [keys, permissions] 1 tags: [keychains, permissions] 1 tags: [kanvas] 1 tags: [integrations] 1 tags: [identity, byoc, orgs] 1 tags: [identity] 1 tags: [helm] 1 tags: [gitops, github-actions, kanvas] 1 tags: [Dock, Pin, Models, designer] 1 tags: [Dock, Pin, Models] 1 tags: [designs, workspaces, environments] 1 tags: [designs, relationships, components, troubleshooting] 1 tags: [designs, relationships, components] 1 tags: [designs, publishing] 1 tags: [designs, export] 1 tags: [designs, Dock] 1 tags: [designs, collaboration, review, comments] 1 tags: [designs, collaboration, review] 1 tags: [designer-overview] 1 tags: [connections, remote-provider, meshery-server] 1 tags: [cloud] 1 tags: [catalog, review] 1 tags: [catalog, publishing] 1 tags: [catalog, designs, publishing] 1 tags: [basics, operator-overview] 1 tags: [basics, designer-overview] 1 tags: [badges, recognition, profile] 1 tags: [academy, roles] 1 categories: "platform" 1 categories: [Identity, Security] 1 categories: [Concepts] 1 categories: "cloud"|
|
||
| As your designs grow in complexity, certain design patterns can impact how smoothly Kanvas responds. Understanding these factors helps you create designs that remain fast and responsive. | ||
|
|
||
| {{< alert type="info" title="Related performance controls" >}} |
There was a problem hiding this comment.
Please revert this deletion
| weight: 4 | ||
| categories: [Designer] | ||
| # tags: [designs] | ||
| tags: [designer-overview] |
There was a problem hiding this comment.
Another needed area of improvement. The taxonomies shouldn't have a compound of two nouns unless its extremely needed or the context requires it, which in this case, it doesn't. tags and categories don't share the same elements so a "designer" tag could be used but tags serve to provide a higher level of specifity within a set of parent subjects so simplifying it to just "designer" in the category is preferred if there aren't any other tags that can be provided in the frontmatter
| description: > | ||
| Operator mode is for operating your Kubernetes clusters and cloud native infrastructure. | ||
| categories: [Operator] | ||
| tags: [operator-overview] |
There was a problem hiding this comment.
Same feedback here regarding the compound naming
| categories: [Designer] | ||
| formats: [video] | ||
| tags: [basics] | ||
| tags: [basics, designer-overview] |
There was a problem hiding this comment.
Another compound naming instance. Same feedback as the others
| categories: [Operator] | ||
| formats: [video] | ||
| tags: [basics] | ||
| tags: [basics, operator-overview] |
There was a problem hiding this comment.
Another compound naming instance. Same feedback as the others
banana-three-join
left a comment
banana-three-join
left a comment
There was a problem hiding this comment.
@nafisa404 Please go through my review above whenever you have time. Thanks!
4 participants
Description
This PR updates the "Pinning Models to the Dock" documentation to use the existing Related Reading mechanism instead of a hardcoded Related Docs link.
Changes
Related Docshyperlink from the Pinning Models to the Dock page.Docktag to the Understanding Tool Modes page so it is automatically surfaced by the existing Related Reading implementation.This keeps related content consistent with the current
related-reading.htmlapproach while minimizing changes.Resolves: #1028
Locally tested