docs: restructure /sync — uv-style sidebar, 7 new pages, voice pass#128
docs: restructure /sync — uv-style sidebar, 7 new pages, voice pass#128yjouffrault wants to merge 1 commit into
Conversation
- New pages: orchestration (schedule sync runs), side-by-side
pattern, migration walkthrough, schema mapping reference,
choosing an adapter, PeeringDB + Device42 adapter stubs.
- Moved: guides/ contents (installation, creation→create, run,
custom-certificates) to docs/docs/ root.
- Split: development.mdx → contributing.mdx (contributor docs)
+ RELEASING.md (maintainer release runbook) at repo root.
- Sidebar: uv-style structure — Get started · Guides · Adapters ·
Reference · Contributing.
- Titles: imperative form for task pages ("Create a sync project"),
noun form for reference.
- Voice pass on all new prose: drop "the team" third-person
paraphrasing, "without X" negation framing, and corporate-speak
verb+adverb constructions; lead with capability + use case,
not implementation type.
- 5 URL redirects via @docusaurus/plugin-client-redirects
(legacy /guides/* paths + /development → /contributing).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Deploying infrahub-sync with
|
| Latest commit: |
9831e8c
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://5bf32f71.infrahub-sync.pages.dev |
| Branch Preview URL: | https://docs-sync-restructure.infrahub-sync.pages.dev |
WalkthroughThis PR restructures the Infrahub Sync documentation from a legacy 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (4)
docs/docs/adapters/peeringdb.mdx (2)
5-7: ⚡ Quick winRemove unused imports.
The stub imports
ReferenceLink,Tabs, andTabItembut doesn't use them. Clean up these imports until the page is fleshed out.🧹 Proposed cleanup
-import ReferenceLink from "../../src/components/Card"; -import Tabs from '`@theme/Tabs`'; -import TabItem from '`@theme/TabItem`'; -🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/docs/adapters/peeringdb.mdx` around lines 5 - 7, Remove the unused imports ReferenceLink, Tabs, and TabItem from the top of the peeringdb.mdx stub by deleting their import statements (the lines that import ReferenceLink from "../../src/components/Card" and Tabs/TabItem from '`@theme/`*'); keep the file otherwise unchanged and re-add these imports only when the components are actually used.
9-9: 💤 Low valueVale sentence-case warning on proper noun.
The pipeline flags "What is PeeringDB?" as violating sentence case, but "PeeringDB" is a proper noun with specific capitalization. If Vale continues to flag this, consider adding a vale-off comment or updating the Vale rule to handle product names.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/docs/adapters/peeringdb.mdx` at line 9, The header "## What is PeeringDB?" is being flagged by Vale for sentence-case but "PeeringDB" is a proper noun; either suppress the lint for this occurrence by wrapping or annotating the header with a Vale disable comment (e.g., add a Vale inline disable/enable around the "## What is PeeringDB?" header) or add "PeeringDB" to the Vale allowed words/wordlist/style configuration so the rule accepts its capitalization; update the docs line containing the header or the Vale config accordingly.docs/docs/adapters/device42.mdx (2)
5-7: ⚡ Quick winRemove unused imports.
The stub imports
ReferenceLink,Tabs, andTabItembut doesn't use them. Clean up these imports until the page is fleshed out.🧹 Proposed cleanup
-import ReferenceLink from "../../src/components/Card"; -import Tabs from '`@theme/Tabs`'; -import TabItem from '`@theme/TabItem`'; -🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/docs/adapters/device42.mdx` around lines 5 - 7, The file imports unused symbols ReferenceLink, Tabs, and TabItem; remove those import statements (the import lines that reference ReferenceLink, Tabs, and TabItem) so there are no unused imports remaining until the page uses those components; if you plan to re-add later, keep a single TODO comment instead of importing unused symbols.
9-9: 💤 Low valueVale sentence-case warning on proper noun.
The pipeline flags "What is Device42?" as violating sentence case, but "Device42" is a proper noun with specific capitalization. If Vale continues to flag this, consider adding a vale-off comment or updating the Vale rule to handle product names.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/docs/adapters/device42.mdx` at line 9, The Vale linter is flagging the heading "What is Device42?" as a sentence-case violation even though "Device42" is a proper noun; fix by either disabling Vale for that heading or adding a Vale exception: add an inline Vale disable comment around the heading (e.g., <!-- vale off --> before the "What is Device42?" heading and <!-- vale on --> after the block) or add a rule/term exception in your Vale config to whitelist "Device42" so the header is no longer flagged.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/docs/contributing.mdx`:
- Line 57: Update the heading "Validate the CLI" to sentence case by
capitalizing only the first word and leaving the acronym as-is (e.g., "Validate
the CLI"); if Vale still flags Infrahub.sentence-case for that heading, add a
Vale directive to disable that rule for this line (disable
Infrahub.sentence-case for the heading) so the acronym "CLI" is accepted; target
the heading text "Validate the CLI" when making the change.
In `@docs/docs/migrating-from-netbox-or-nautobot.mdx`:
- Line 100: Update the heading "## Phase 5 — Migrate workflows" to sentence-case
by lowercasing the subtitle after the em dash; find the heading string "## Phase
5 — Migrate workflows" and change it to "## Phase 5 — migrate workflows" so it
passes the Infrahub.sentence-case Vale check.
- Line 120: Update the MDX heading "## Differences between migrating from NetBox
versus Nautobot" to sentence-case to satisfy Vale; change it to something like
"## Differences between migrating from NetBox and Nautobot" (keep proper nouns
like NetBox and Nautobot capitalized) so the heading matches the
Infrahub.sentence-case rule.
In `@docs/docs/readme.mdx`:
- Line 5: The Vale spellcheck is flagging “ServiceNow-style CMDBs” because the
token CMDBs is not in the Vale exceptions file; open spelling-exceptions.txt
(the Vale spelling exceptions list) and add a new entry "CMDBs" (exact casing)
on its own line so Vale will accept the phrase in docs/docs/readme.mdx; commit
the change to unblock the build.
In `@docs/docs/using-netbox-or-nautobot-with-infrahub.mdx`:
- Line 59: The MDX sentence contains the flagged word "queryable"; fix by either
adding "queryable" to the Vale exceptions (spelling-exceptions.txt) or by
rephrasing the sentence to avoid the term (e.g., change "the same data is
queryable via Infrahub's graph traversal capabilities" to "the same data can be
queried via Infrahub's graph traversal capabilities"); update the docs line
containing "queryable via Infrahub's graph traversal capabilities" accordingly
and run Vale/markdownlint to confirm the validation passes.
---
Nitpick comments:
In `@docs/docs/adapters/device42.mdx`:
- Around line 5-7: The file imports unused symbols ReferenceLink, Tabs, and
TabItem; remove those import statements (the import lines that reference
ReferenceLink, Tabs, and TabItem) so there are no unused imports remaining until
the page uses those components; if you plan to re-add later, keep a single TODO
comment instead of importing unused symbols.
- Line 9: The Vale linter is flagging the heading "What is Device42?" as a
sentence-case violation even though "Device42" is a proper noun; fix by either
disabling Vale for that heading or adding a Vale exception: add an inline Vale
disable comment around the heading (e.g., <!-- vale off --> before the "What is
Device42?" heading and <!-- vale on --> after the block) or add a rule/term
exception in your Vale config to whitelist "Device42" so the header is no longer
flagged.
In `@docs/docs/adapters/peeringdb.mdx`:
- Around line 5-7: Remove the unused imports ReferenceLink, Tabs, and TabItem
from the top of the peeringdb.mdx stub by deleting their import statements (the
lines that import ReferenceLink from "../../src/components/Card" and
Tabs/TabItem from '`@theme/`*'); keep the file otherwise unchanged and re-add
these imports only when the components are actually used.
- Line 9: The header "## What is PeeringDB?" is being flagged by Vale for
sentence-case but "PeeringDB" is a proper noun; either suppress the lint for
this occurrence by wrapping or annotating the header with a Vale disable comment
(e.g., add a Vale inline disable/enable around the "## What is PeeringDB?"
header) or add "PeeringDB" to the Vale allowed words/wordlist/style
configuration so the rule accepts its capitalization; update the docs line
containing the header or the Vale config accordingly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 23aaf314-0de6-454b-b476-172e1bbfb438
⛔ Files ignored due to path filters (1)
docs/package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (24)
.vale/styles/spelling-exceptions.txtREADME.mdRELEASING.mddocs/docs/adapters/choosing-an-adapter.mdxdocs/docs/adapters/device42.mdxdocs/docs/adapters/nautobot.mdxdocs/docs/adapters/netbox.mdxdocs/docs/adapters/peeringdb.mdxdocs/docs/contributing.mdxdocs/docs/creating-a-sync-project.mdxdocs/docs/custom-certificates.mdxdocs/docs/guides/creation.mdxdocs/docs/guides/custom-certificates.mdxdocs/docs/installation.mdxdocs/docs/migrating-from-netbox-or-nautobot.mdxdocs/docs/orchestration.mdxdocs/docs/readme.mdxdocs/docs/reference/config.mdxdocs/docs/reference/schema-mapping.mdxdocs/docs/running-a-sync.mdxdocs/docs/using-netbox-or-nautobot-with-infrahub.mdxdocs/docusaurus.config.tsdocs/package.jsondocs/sidebars.ts
💤 Files with no reviewable changes (2)
- docs/docs/guides/creation.mdx
- docs/docs/guides/custom-certificates.mdx
| uv run mypy infrahub_sync/ --ignore-missing-imports | ||
| ``` | ||
|
|
||
| ### Validate the CLI |
There was a problem hiding this comment.
Resolve Vale sentence-case warning.
The pipeline reports a Vale warning that contradicts the PR's claim of "0 errors." The heading may need adjustment to satisfy the Infrahub.sentence-case rule, though the current capitalization of "CLI" as an acronym appears correct.
🧰 Tools
🪛 GitHub Actions: Pull Request on main/stable / 1_linter _ validate-documentation-style.txt
[warning] 57-57: Vale (Infrahub.sentence-case) warning: 'Validate the CLI' should use sentence case.
🪛 GitHub Actions: Pull Request on main/stable / linter _ validate-documentation-style
[warning] 57-57: Vale (Infrahub.sentence-case) warning: 'Validate the CLI' should use Infrahub.sentence-case sentence case.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/docs/contributing.mdx` at line 57, Update the heading "Validate the CLI"
to sentence case by capitalizing only the first word and leaving the acronym
as-is (e.g., "Validate the CLI"); if Vale still flags Infrahub.sentence-case for
that heading, add a Vale directive to disable that rule for this line (disable
Infrahub.sentence-case for the heading) so the acronym "CLI" is accepted; target
the heading text "Validate the CLI" when making the change.
|
|
||
| During side-by-side operation, the same model may be edited in both tools. Decide upfront which tool is authoritative for each model and document the decision in the project configuration. If both tools allow edits to the same model, conflicts will eventually occur — and Infrahub Sync's default behavior is for the source system to win. | ||
|
|
||
| ## Phase 5 — Migrate workflows |
There was a problem hiding this comment.
Fix heading to pass Vale sentence-case check.
The pipeline flags this heading as violating the Infrahub.sentence-case rule. Based on the Vale error, this heading should be adjusted to pass the sentence-case validation.
As per coding guidelines, Markdown and MDX files in docs must pass markdownlint-cli2 checks, and the pipeline shows this is currently failing Vale validation.
🧰 Tools
🪛 GitHub Actions: Pull Request on main/stable / 1_linter _ validate-documentation-style.txt
[warning] 100-100: Vale (Infrahub.sentence-case) warning: 'Phase 5 — Migrate workflows' should use sentence case.
🪛 GitHub Actions: Pull Request on main/stable / linter _ validate-documentation-style
[warning] 100-100: Vale (Infrahub.sentence-case) warning: 'Phase 5 — Migrate workflows' should use sentence case.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/docs/migrating-from-netbox-or-nautobot.mdx` at line 100, Update the
heading "## Phase 5 — Migrate workflows" to sentence-case by lowercasing the
subtitle after the em dash; find the heading string "## Phase 5 — Migrate
workflows" and change it to "## Phase 5 — migrate workflows" so it passes the
Infrahub.sentence-case Vale check.
|
|
||
| Many teams reach a stable side-by-side state and stay there indefinitely. See [Use NetBox or Nautobot with Infrahub](./using-netbox-or-nautobot-with-infrahub.mdx). | ||
|
|
||
| ## Differences between migrating from NetBox versus Nautobot |
There was a problem hiding this comment.
Fix heading to pass Vale sentence-case check.
The pipeline flags this heading as violating the Infrahub.sentence-case rule. Based on the Vale error, this heading should be adjusted to pass the sentence-case validation.
As per coding guidelines, Markdown and MDX files in docs must pass markdownlint-cli2 checks, and the pipeline shows this is currently failing Vale validation.
🧰 Tools
🪛 GitHub Actions: Pull Request on main/stable / 1_linter _ validate-documentation-style.txt
[warning] 120-120: Vale (Infrahub.sentence-case) warning: 'Differences between migrating from NetBox versus Nautobot' should use sentence case.
🪛 GitHub Actions: Pull Request on main/stable / linter _ validate-documentation-style
[warning] 120-120: Vale (Infrahub.sentence-case) warning: 'Differences between migrating from NetBox versus Nautobot' should use sentence case.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/docs/migrating-from-netbox-or-nautobot.mdx` at line 120, Update the MDX
heading "## Differences between migrating from NetBox versus Nautobot" to
sentence-case to satisfy Vale; change it to something like "## Differences
between migrating from NetBox and Nautobot" (keep proper nouns like NetBox and
Nautobot capitalized) so the heading matches the Infrahub.sentence-case rule.
| --- | ||
|
|
||
| Infrahub Sync is a Python package that synchronizes data between Infrahub and external infrastructure systems. It connects to NetBox, Nautobot, IP Fabric, Slurp’it, Cisco ACI, ServiceNow-style systems, and other tools through a library of pre-built adapters, and handles both the communication with each system and the translation of data between different schemas. Sync projects are defined declaratively in YAML; the CLI generates the adapter code, calculates the diff, and applies changes. | ||
| Infrahub Sync synchronizes infrastructure data between Infrahub and external systems — NetBox, Nautobot, IP Fabric, Slurp’it, Cisco ACI, Peering Manager, ServiceNow-style CMDBs, and any system with a REST/JSON API. Use it to migrate from a legacy system of record, run two systems side-by-side, or keep Infrahub in sync with another source of truth. Define a sync project declaratively in YAML, and the CLI generates the adapter code, calculates the diff, and applies only the deltas on each run. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if CMDBs is in the Vale spelling exceptions
if [ -f ".vale/styles/spelling-exceptions.txt" ]; then
echo "=== Checking spelling-exceptions.txt for CMDBs ==="
grep -i "cmdb" .vale/styles/spelling-exceptions.txt || echo "CMDBs not found in exceptions"
else
echo "ERROR: .vale/styles/spelling-exceptions.txt not found"
fiRepository: opsmill/infrahub-sync
Length of output: 146
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "=== Check Vale spelling exceptions file existence ==="
ls -la .vale/styles/spelling-exceptions.txt || true
echo
echo "=== Search for cmdb-related entries in spelling-exceptions.txt ==="
if [ -f ".vale/styles/spelling-exceptions.txt" ]; then
rg -n -i 'cmdb' .vale/styles/spelling-exceptions.txt || true
echo
echo "=== Show first 80 lines of spelling-exceptions.txt (for context) ==="
sed -n '1,80p' .vale/styles/spelling-exceptions.txt
fi
echo
echo "=== Confirm 'CMDBs' occurrence in docs/docs/readme.mdx ==="
sed -n '1,40p' docs/docs/readme.mdx | nl -ba | sed -n '1,40p'
rg -n '\bCMDBs\b' docs/docs/readme.mdx || trueRepository: opsmill/infrahub-sync
Length of output: 1273
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "=== Search for cmdb-related entries in spelling-exceptions.txt ==="
if [ -f ".vale/styles/spelling-exceptions.txt" ]; then
rg -n -i 'cmdb' .vale/styles/spelling-exceptions.txt || true
else
echo "ERROR: .vale/styles/spelling-exceptions.txt not found"
fi
echo
echo "=== Show the exact line(s) containing CMDBs in docs/docs/readme.mdx (if any) ==="
rg -n '\bCMDBs\b' docs/docs/readme.mdx || true
echo
echo "=== Show surrounding text around 'CMDB'/'CMDBs' if present ==="
if rg -n -i 'cmdb' docs/docs/readme.mdx >/dev/null 2>&1; then
rg -n -i 'cmdb' -C 3 docs/docs/readme.mdx
else
echo "No 'cmdb' substring found in docs/docs/readme.mdx"
fi
echo
echo "=== Show lines 1-15 of docs/docs/readme.mdx for context (with line numbers) ==="
sed -n '1,15p' docs/docs/readme.mdx | cat -nRepository: opsmill/infrahub-sync
Length of output: 4574
Add “CMDBs” to Vale spelling exceptions
docs/docs/readme.mdx (line 5) includes “ServiceNow-style CMDBs”, but .vale/styles/spelling-exceptions.txt contains no cmdb/CMDBs exception entry. Add CMDBs to .vale/styles/spelling-exceptions.txt to unblock the Vale build.
🧰 Tools
🪛 GitHub Actions: Pull Request on main/stable / 1_linter _ validate-documentation-style.txt
[error] 5-5: Vale (Infrahub.spelling) error: Did you really mean 'CMDBs'?
🪛 GitHub Actions: Pull Request on main/stable / linter _ validate-documentation-style
[error] 5-5: Vale (Infrahub.spelling) error: Did you really mean 'CMDBs'? Infrahub.spelling.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/docs/readme.mdx` at line 5, The Vale spellcheck is flagging
“ServiceNow-style CMDBs” because the token CMDBs is not in the Vale exceptions
file; open spelling-exceptions.txt (the Vale spelling exceptions list) and add a
new entry "CMDBs" (exact casing) on its own line so Vale will accept the phrase
in docs/docs/readme.mdx; commit the change to unblock the build.
|
|
||
| ### Cable tracing | ||
|
|
||
| NetBox and Nautobot both include a cable tracing feature that follows connections through patch panels and intermediate devices. Infrahub does not have a single-click cable trace view, but the same data is queryable via Infrahub's graph traversal capabilities. For visualization, build a custom artifact or query with GraphQL from external tools. |
There was a problem hiding this comment.
Fix Vale spelling error for "queryable".
The pipeline flags "queryable" as a spelling error. To resolve this, either add "queryable" to .vale/styles/spelling-exceptions.txt or rephrase the sentence (e.g., "the same data can be queried via Infrahub's graph traversal capabilities").
Proposed fix: Add to spelling exceptions
Add the following line to .vale/styles/spelling-exceptions.txt:
queryable
Alternatively, rephrase the sentence:
-NetBox and Nautobot both include a cable tracing feature that follows connections through patch panels and intermediate devices. Infrahub does not have a single-click cable trace view, but the same data is queryable via Infrahub's graph traversal capabilities. For visualization, build a custom artifact or query with GraphQL from external tools.
+NetBox and Nautobot both include a cable tracing feature that follows connections through patch panels and intermediate devices. Infrahub does not have a single-click cable trace view, but the same data can be queried via Infrahub's graph traversal capabilities. For visualization, build a custom artifact or query with GraphQL from external tools.As per coding guidelines, Markdown and MDX files in docs must pass markdownlint-cli2 checks, and the pipeline shows this is currently failing Vale validation.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| NetBox and Nautobot both include a cable tracing feature that follows connections through patch panels and intermediate devices. Infrahub does not have a single-click cable trace view, but the same data is queryable via Infrahub's graph traversal capabilities. For visualization, build a custom artifact or query with GraphQL from external tools. | |
| NetBox and Nautobot both include a cable tracing feature that follows connections through patch panels and intermediate devices. Infrahub does not have a single-click cable trace view, but the same data can be queried via Infrahub's graph traversal capabilities. For visualization, build a custom artifact or query with GraphQL from external tools. |
🧰 Tools
🪛 GitHub Actions: Pull Request on main/stable / 1_linter _ validate-documentation-style.txt
[error] 59-59: Vale (Infrahub.spelling) error: Did you really mean 'Infrahub.spelling queryable'?
🪛 GitHub Actions: Pull Request on main/stable / linter _ validate-documentation-style
[error] 59-59: Vale (Infrahub.spelling) error: Did you really mean Infrahub.spelling 'queryable'?
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/docs/using-netbox-or-nautobot-with-infrahub.mdx` at line 59, The MDX
sentence contains the flagged word "queryable"; fix by either adding "queryable"
to the Vale exceptions (spelling-exceptions.txt) or by rephrasing the sentence
to avoid the term (e.g., change "the same data is queryable via Infrahub's graph
traversal capabilities" to "the same data can be queried via Infrahub's graph
traversal capabilities"); update the docs line containing "queryable via
Infrahub's graph traversal capabilities" accordingly and run Vale/markdownlint
to confirm the validation passes.
2 participants
Summary by CodeRabbit
Release Notes
Documentation
Chores
Restructure the
/sync/docs section. Single production PR — goes live todocs.infrahub.app/syncon merge.docs/docs/guides/to rootdevelopment.mdx→contributing.mdx+RELEASING.md(maintainer runbook moves to repo root)@docusaurus/plugin-client-redirectsFull project plan with rationale: Confluence — Overview project plan.
Final sidebar
What needs reviewer attention
Sorted by how much new content needs verification.
Net-new prose — read end-to-end
docs/docs/orchestration.mdxdocs/docs/using-netbox-or-nautobot-with-infrahub.mdxdocs/docs/migrating-from-netbox-or-nautobot.mdxSKIP_UNMATCHED_DSTbehavior description, and the differences-between-NetBox-and-Nautobot section.docs/docs/reference/schema-mapping.mdxinfrahub_sync/__init__.py:114-130(the prior table inconfig.mdxwas wrong). NetBox + Nautobot worked examples are illustrative — verify field names.docs/docs/adapters/choosing-an-adapter.mdxRELEASING.md(repo root)development.mdx; no content changes, only location. Verify it still reads as a coherent runbook on its own.Stub pages — minimal content, just confirm framing
docs/docs/adapters/peeringdb.mdx— "Under Construction" stub matching the LibreNMS/Observium pattern.docs/docs/adapters/device42.mdx— same.Rewrites — compare against original
creating-a-sync-project.mdxguides/creation.mdx, but reshaped: dropped "this guide will walk you through" opener; "Step 1/2/3/4" headings → action-named (Define source & destination / Set the sync order / Map the schema fields / Tune sync behavior). Nautobot → Infrahub example preserved.custom-certificates.mdxguides/custom-certificates.mdx, but reshaped: dropped "this guide will walk you through" opener; collapsed 4 single-command steps into 2 action-named sections. Adds a note that paths shown are Debian/Ubuntu-specific.contributing.mdxdevelopment.mdx. Content above the "Publishing a release" section preserved verbatim. The 180-line Release Runbook moved to/RELEASING.md. Opens with a one-line pointer to RELEASING.md.Targeted edits — small surface area
docs/docs/reference/config.mdxschema-mapping.mdx), replaced with brief mention + pointer. Structural tables (Mapping models / fields / filters / transforms) unchanged.docs/docs/adapters/netbox.mdxdocs/docs/adapters/nautobot.mdxdocs/docs/readme.mdx(overview)README.md(repo root)/sync/URLs and new imperative titles ("Create a sync project" etc.)..vale/styles/spelling-exceptions.txtPage renames
All task-page titles converted from gerund to imperative form (matches the imperative voice in the body prose, and matches Stripe / FastAPI / Pulumi convention for how-to pages):
Reference page titles kept as noun-phrase (they describe a thing, not an action).
URL redirects
Configured via
@docusaurus/plugin-client-redirectsindocs/docusaurus.config.ts(pinned to3.10.0to match Docusaurus core):/sync/guides/installation/sync/installation/sync/guides/creation/sync/creating-a-sync-project/sync/guides/run/sync/running-a-sync/sync/guides/custom-certificates/sync/custom-certificates/sync/development/sync/contributingVerification
cd docs && npm run buildsucceedsnpx markdownlint-cli2— clean across 30 files (0 errors)vale docs/docs/— 0 errors in new/touched content. Remaining errors are all in pre-existingmedia/infrahub_sync_process.excalidraw.svg(embedded font tokens — out of scope)build/<old-path>/http://localhost:3010/Out of scope (deferred)
Tracked as Open Issues on the Confluence project plan:
Test plan