docs: update Otto the otter mascot logo#9148
Closed
petercrocker wants to merge 27 commits into
Closed
Conversation
Restructure the docs sidebar by capability so each feature has one home in the nav. No .mdx files are moved or renamed; no individual page URLs change. New top-level sections: - Introduction - Getting Started - Deploying & Managing Infrahub - Schema & Data Modeling - Version Control & Branching - Data Management - IPAM & Resource Management - Transforms & Artifacts - Generators - Git Integration - Events & Integrations (with Observability subgroup) - User Management & Security - Solutions - Reference - Academy (unchanged) - Contributing (unchanged + topics/local-demo-environment) - Release Notes (unchanged) - FAQ Eleven external "↗" links are stubbed with TODO URLs to fill in before merge (grep "TODO-FILL-IN-"). Phase 1 of a multi-sprint effort to make the docs easier to navigate without changing content. Phase 2 (per-feature content reorganization, e.g. Groups hub + spokes) follows in subsequent PRs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This branch is a concrete worked example for the docs team showing how
hub + spokes with Diataxis-aligned pages compares to the current
topic+guide pair for the Groups feature. It is NOT intended for merge.
WHAT THIS DEMONSTRATES
1. A hub page at /docs/groups/ — pure explanation, no task content.
2. Six spoke pages, each a self-contained how-to (no Step 1/2/3 linear
narrative, no shared running example):
- create, add-members, remove-members, delete, query-members,
use-in-automation
3. A tutorial at /docs/academy/getting-started/groups preserving the
original TagConfigGroup linear walkthrough in its proper home.
4. Sidebar uses a nested "Groups" category under Data Management with
the hub as the clickable landing page.
CONTENT PROVENANCE
- Hub derived from topics/groups.mdx with minor edits (decision aid
added, misplaced GraphQL snippet moved to Query spoke).
- Spokes extract, rewrite, and in one case substantially expand
(use-in-automation) the current guide and topic content.
- Tutorial is the original guide's Step 1/2/3 content reframed as a
proper tutorial with learning-oriented preamble and "what you
learned" closer.
- Nothing invented — every factual claim traces to existing docs.
WHAT A REAL MIGRATION WOULD DO AND THIS DEMO DOES NOT
- Delete docs/docs/topics/groups.mdx and docs/docs/guides/groups.mdx
(kept here so inbound links from 7 other topic pages don't break).
- Update those 7 inbound links to point at the new URLs.
- Add @docusaurus/plugin-client-redirects to redirect
/docs/topics/groups and /docs/guides/groups to the new hub for
external bookmarks.
Built on top of the navigation restructure in #8954.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Iteration on PR #8958 based on team feedback: - Wrap each top-level section (Get started, Capabilities, Operate & extend, Reference & learn, Project) in a non-collapsible category so section headers use the same DOM and styling as the original Overview/Guides/Topics headers — no custom HTML or CSS needed for spacing/padding. - Split Academy into Getting Started + Tutorials subgroups; rename Groups tutorial to "Organize objects with groups" and move it to academy/tutorials/. - Move Resource Manager (topic + guide) back into Data Management alongside Groups; rename "IPAM & Resource Management" section to just "IPAM". - Drop the "Observability" subgroup; place Log Forwarding (topic + guide) flat next to Activity Log under Events & Integrations; move Telemetry to Deploying & Managing Infrahub. - Add canonical "Development Resources" section containing Developer Guide, Local Demo Environment, and Testing Framework; cross-link from Transforms & Artifacts, Generators, and Contributing using Docusaurus type: 'ref'. - Move FAQ into Get started. - Reduce nested-category caret size and color-match it to label text (e.g. Groups under Data Management) so it reads as connected to its parent rather than another peer toggle. - Update hub page Learn-by-doing link to the renamed Academy tutorial. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…enerator group accuracy - Rename top-level "Capabilities" section to "Features" (label still open for team review — alternatives in Open Questions Confluence doc). - Split the former "Reference & learn" section in two: "Learn" (now positioned right after Get started; contains Academy content) and "Reference" (kept later in sidebar; sub-categories flattened directly under it). - Fix accuracy issues in groups/use-in-automation.mdx: rewrite the Generator section to correctly describe CoreStandardGroup as the Generator's input target and CoreGeneratorGroup as the auto-managed output (Infrahub tracks produced objects via SDK tracking; the user doesn't declare it). Fix the "chain through the pipeline" pattern step 2 (Generator targets a CoreStandardGroup, not a Query group, per the schema reference). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Move Integrations from Features → Operate & extend (positioned between Development Resources and Solutions). External integrations consume Infrahub's interfaces; they aren't Infrahub features. - Drop Schema Library external link from the sidebar — it's a community-maintained external resource, not an Infrahub feature. Will be referenced inline in Schema content instead (tracked in Open Questions). - Rename "Version Control & Branching" → "Branches & Change Control" per Damien's feedback that "version control" is too technical and doesn't communicate scope. New name covers the branching mechanism plus the change-review pipeline (proposed changes, checks, approvals). - Default-collapse the Introduction and Getting Started categories inside Get started (previously open by default — inconsistent with every other category). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Codifies the workflow for migrating a single Infrahub docs feature page (Layer 2 capability content) from the legacy topic+guide pair to a single merged page or hub+spokes pattern. Captures the Groups precedent, decision rules for choosing the migration pattern, PR description template, cross-reference handling, and the end-of- migration content-audit step. Triggered by feature names like "let's migrate profiles" or "start the Resource Manager migration." Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: migrate Profiles per docs revamp
Migrate the Profiles feature page from the legacy topic+guide pair to
the hub + spokes pattern (Groups precedent), preserve the tutorial
content in Academy, and establish the redirects-pending convention.
Structure:
docs/docs/profiles/
├── index.mdx ← hub (former topic content)
├── priority-and-inheritance.mdx
├── create.mdx
├── assign.mdx
├── override-values.mdx
├── update.mdx
└── use-multiple.mdx
docs/docs/academy/tutorials/profiles.mdx ← preserved tutorial
Content changes:
- Topic → hub. Opening sentence softened to remove the "configuration
templates" phrasing that collides with the actual Object Templates
feature. Added a "Profiles vs Object Templates" comparison section
closing a real gap in the existing docs.
- Inheritance mechanism + Profile priority system extracted into a
dedicated concept spoke. Reasoning explained in the PR body so
reviewers can push back if they prefer it on the hub.
- Guide → Academy tutorial. Light reframing only (preamble + tutorial
language); all running examples and content preserved.
- Five short how-to spokes added (Create / Assign / Override values /
Update / Use multiple) with generic placeholder syntax.
Other changes:
- docs/redirects-pending/ convention established with README and
profiles.yml. Future feature-migration PRs drop YAML files here;
end-of-Phase-2 cleanup PR aggregates them into the redirects plugin
config.
- docs/docs/groups/index.mdx — removed the redundant "Common tasks"
link list (spokes already appear in the sidebar).
- dev/skills/migrate-feature-page/SKILL.md — updated for the
redirects-pending convention and the no-Common-tasks-list pattern.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs(profiles): point tutorial cross-links at canonical paths
The tutorial was created by copying the legacy guide content, which
linked back to topics/profiles.mdx and used a #profile-priority-system
anchor on that same legacy file. Those links worked during iteration
because the legacy file is still on disk, but they would 404 in the
build once the cleanup PR deletes the legacy file. Updated 4 links to
point at the new canonical paths:
- 3 links pointing at topics/profiles → now profiles/index.mdx
- 1 link with #profile-priority-system anchor → now points at
profiles/priority-and-inheritance.mdx (where that section lives)
Surfaced during the end-of-migration content audit.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs(profiles): apply AGENTS.md style compliance + update skill
- Replace two uses of "Just" in profiles/index.mdx with "Like".
AGENTS.md "Never Do" lists "just" as a forbidden word; both instances
were preserved from the original topics/profiles.mdx but they're now
shipping under the new structure, so fix at the migration moment.
- Update migrate-feature-page skill to require running
`uv run invoke docs.lint` before committing (per docs/AGENTS.md
"Documentation Workflow") and to scan for the AGENTS.md "Never Do"
words that the linters miss. Surfaced during the Profiles audit.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Update docs/docs/profiles/use-multiple.mdx
Co-authored-by: Baptiste <32564248+BaptisteGi@users.noreply.github.com>
* docs(profiles): address Baptiste review — remove tutorial, hub picks up composition patterns
- Remove the Profiles Academy tutorial; defer rewrite to a real-world
scenario ("Managing network interfaces at scale using Profiles").
- Move "Common composition patterns" into the Profiles hub
(preserving Baptiste's accepted suggestion on use-multiple.mdx).
- Update use-multiple.mdx link to anchor at the hub section.
- Update redirects-pending entry: tutorial removed, legacy URLs still
redirect to the new hub.
- Update migrate-feature-page skill (Step 4): preserve UI / SDK / GraphQL
interface coverage from the existing guide; do not reduce to GraphQL-only.
Deferred items captured on Confluence Open Questions:
- UI / SDK example backfill in the five Profiles spokes
- Worked example for relationships + Profiles
- Tutorial rewrite as practical network-interface-at-scale scenario
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Apply suggestion from @BaptisteGi
* Apply suggestion from @BaptisteGi
* fix: bring back the old content + fix linting
---------
Co-authored-by: Yvonne <yvonne@opsmill.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Baptiste <32564248+BaptisteGi@users.noreply.github.com>
Co-authored-by: Baptiste <girard.baptiste@hotmail.fr>
Two lessons from PR #9114 (Profiles migration) review: - Step 3 (Pattern decision) — when extracting an Academy tutorial, sanity- check whether it's actually scenario-shaped or just the guide with sequence numbers. Feature-oriented tutorials don't earn their slot; drop them with a follow-up entry on Open Questions for a real-world rewrite. Profiles set this precedent. - Step 10 (Lint, commit, push) — broaden the AGENTS.md forbidden-words check to cover every file changed in the PR (skill files, dev docs, agent guides), not only the migrated docs pages. The rule is global. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: migrate Computed Attributes page per docs revamp Single-page merge organized by computed-attribute kind. The choosing table is promoted to the top so the comparison is visible before either kind's section. Each kind section now contains its concept, restrictions, and how-to(s) in one place. Recommendations from the legacy guide are folded inline. Legacy guide URL redirects to the canonical topic page. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: move computed attributes to the correct folder --------- Co-authored-by: Yvonne <yvonne@opsmill.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Baptiste <girard.baptiste@hotmail.fr>
…ended redirects-pending schema
Three workflow improvements going into the B&CC section migration:
- Skill now supports section-wide migrations (a whole section like
Branches & Change Control with multiple features migrated together),
not only single-feature migrations. Adds branch-naming convention,
audit-all-files-in-section guidance, and a "Recommendations for large
or section-wide migrations" section with patterns for one-at-a-time
hub conversion, hub-after-extraction review, cross-link verification,
user-perspective walk-through, and per-page TodoWrite tracking.
- Pre-PR audit (was end-of-migration audit). Moved from Step 11 to Step 9
so issues land in the PR clean rather than as fix-up commits afterward.
- redirects-pending schema extended with two new sections:
* new_pages — canonical URLs for pages introduced by the migration
* cross_links_to_update — inventory of stale internal links in OTHER
files that should be rewritten at cleanup time
Both are metadata for humans/cleanup PR; only `redirects` is consumed
by the redirect plugin.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Six concrete updates plus a meta-rule, all from review of PR #9125. Meta-rule: never recommend silently. When the spec-review or implementation surfaces additional changes beyond what the recommendations doc states (merging pages, missing spokes, hub click-targets, renames), present and ask the user — don't apply unilaterally. Step 2.5 (NEW): Spec review against skill rules. When a recommendations doc exists, do a critical review pass against a checklist of common gaps before implementing: topic+guide pairs being preserved as separate moves, shared name roots indicating merge candidates, hub categories without clickable links, tutorial-shaped guides not extracted, missing common spokes, leftover (Topic)/(Guide) labels. Step 4 (Single-page merge): Use docs/<feature>/index.mdx pattern by default, even when there are no spokes. Computed Attributes (PR #9120) is the precedent. Keeps URLs stable across future restructures. Step 4 (Hub+spokes): Critical callout — every hub category must have link: { type: 'doc', id: '<feature>/index' } in sidebars.ts so the label is clickable. We hit this exact bug on Git Integration in PR #9125; documented as a recurring trap. Step 4 (Decision rules table): Added "shared name root + related procedural scope" as a single-page-merge signal. Catches cases like branch-synchronization + selective-branch-sync that look like two features but are one. Step 9 (Audit): Strengthened language — the audit is a real read-through, not a tool run. Build/lint/word-check are necessary but not sufficient. For section-wide migrations, delegate to an Explore agent. Specific call-out: don't claim audit clean from just a build pass. Step 11 (Lint): Vale failures block CI; install if missing (brew install vale or download from releases). Added "verify each lint tool actually ran" guidance — uv run invoke docs.lint exits 0 even when Vale is missing. Documented common Vale rules (spelling, swap, branded-terms-case-swap, eg-ie, sentence-case) and the .vale.ini exclusion pattern for dev-internal docs. NEW section: Spec drift during implementation is normal. Loop clarified — discover gap → present per meta-rule → user decides → update recommendations doc → implement against updated spec. Don't quietly diverge. NEW distinction in "What's NOT done": cross-section content stays out of scope, but moving an entire sub-category's sidebar position is in-scope when the recommendations doc specifies. PR #9125's Git-Integration-into-B&CC move is the precedent. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: migrate Branches & Change Control section per docs revamp Section-wide migration per the canonical spec: https://opsmill.atlassian.net/wiki/spaces/Product/pages/572358657 - Branches: hub + 5 spokes (create/merge/rebase/delete/resolve-conflicts) - Proposed Changes: hub + 3 spokes (lifecycle/review-and-stamp/resolve-conflict) - Checks & Validation: hub-only with link to Academy tutorial - guides/check.mdx → academy/tutorials/build-a-check.mdx (tutorial extraction) - Change Approval Workflow → "Change Approval Policy"; content reframed from tutorial to recipe (drop "Step N", swap personas for placeholders) - Git Integration moved into B&CC as nested hub+spokes (Connect a repository / infrahub.yml configuration / Selective branch synchronization — last is a single-page merge of the topic + the selective-branch-sync guide; "Step N" headers replaced with action-named sections) - Sidebar: B&CC restructured; standalone Git Integration top-level removed; Build a check tutorial added to Learn → Tutorials - redirects-pending/branches-and-change-control.yml with redirects, new_pages, and cross_links_to_update sections Legacy files (topics/branching, topics/proposed-change, topics/check, topics/repository, topics/infrahub-yml, topics/branch-synchronization, guides/check, guides/repository, guides/selective-branch-sync) left on disk for URL stability during iteration; deleted in cleanup PR. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: fix Vale documentation-style errors and warnings CI's validate-documentation-style check (Vale) was failing on the B&CC migration PR. Fixed each error and updated the skill to require Vale to pass before committing (the prior guidance treated Vale as optional, which let these slip through). Errors fixed: - proposed-changes/index.mdx — capitalize Transformations / Generators (Infrahub.branded-terms-case-swap) - git-integration/branch-synchronization.mdx — "repo's" → "repository's" (Infrahub.swap) - branches/delete.mdx — rephrase "unmerged" to "a branch that hasn't been merged" (Infrahub.spelling) Warnings fixed (all in newly authored content): - branches/create.mdx, guides/change-approval-workflow.mdx — replace "e.g." with "for example" (Infrahub.eg-ie) Configuration: - .vale.ini: exclude docs/redirects-pending/** from style checks (dev-internal team workflow file, not user-facing) Skill update: - migrate-feature-page Step 11: Vale errors now explicitly required to pass; install instructions added; common Vale rules documented; guidance on dev-internal exclusions added. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * Apply suggestions from code review Co-authored-by: Baptiste <32564248+BaptisteGi@users.noreply.github.com> * docs: fix delete branch * docs: do not update the guide - copy to dedicated folder * docs: udpate change * docs: fix links * docs: rollback not needed changes * chore: ignore wroking folder from yaml lint * docs: add guide content --------- Co-authored-by: Yvonne <yvonne@opsmill.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Baptiste <32564248+BaptisteGi@users.noreply.github.com> Co-authored-by: Baptiste <girard.baptiste@hotmail.fr>
docs: move menu content
docs: move resource manager
Apply the Phase 2 V3 navigation structure to docs/sidebars.ts only. No content files moved; no URLs changed; no redirects required. Top-level structure goes from 6 to 9 sections: - Get started (unchanged) - Learn (unchanged) - Schema & Data (NEW; replaces parts of Features) - Branches & Change Control (NEW; promoted from Features sub-cat) - Automation & Outputs (NEW; replaces parts of Features; gains Integrations from Operate) - Deployment & Management (renamed from "Operate & extend") - Development Resources (NEW top-level; promoted from Operate sub-cat) - Reference (unchanged) - Project (unchanged; includes Release Notes) Inside the new sections: - Schema & Data: Schema (hub + 6 spokes) / Computed Attributes / Menu Customization / Templates / Resource Manager (hub + 4 spokes from #9117) / IPAM / Objects / Groups (already migrated) / Profiles (already migrated) - Branches & Change Control: structure already migrated in PR #9125 - Automation & Outputs: Generators / Transformations / Artifacts / Artifact & File Storage / Events / Webhooks / Integrations - Deployment & Management: 13 flat items + User Management & Security sub-cat. Lifecycle sub-grouping (Plan & install / Configure / Run / Observe / Maintain & upgrade) deferred to a follow-up PR once Fatih picks an option. - Development Resources: 3 standalone pages + APIs & interfaces sub-cat Removed: - Solutions sub-cat (per V3 decision) - Integrations from Operate (now under Automation & Outputs) - Development Resources from Operate (now its own top-level) Unmigrated content still references existing legacy `topics/X` and `guides/X` paths so every click leads to real content. New pages referenced in the recommendation docs (About Objects, Build a generator, Write a Jinja2 transformation, etc.) are intentionally omitted from the sidebar; they get added in per-feature migration PRs that author the content. Empty/no-hub sub-cats use `link: { type: 'generated-index' }` so Docusaurus auto-generates a clean category landing. Validation: - npm run build succeeds (every doc id: reference resolves) - Spot-checked all sections in the local dev server Refs: V3 outline at https://opsmill.atlassian.net/wiki/spaces/Product/pages/577568769 Co-authored-by: Yvonne <yvonne@opsmill.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replace the previous otto.png with the new flat-style blue otter icon.
github-actions
Bot
added
the
type/documentation
Contributor
Author
|
Closing in favor of #9254, which is rebased directly on |
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
3 participants
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
Replaces the Otto mascot image shown on the FAQ page with the new flat-style blue otter logo.
Changes
docs/docs/media/otto.pngwith the updated logo (new flat-style illustration, 1113×1112px)Test Plan