Skip to content

docs: link post-it diagrams to API pages and adopt the generated triangle marker#623

Merged
DavidCozens merged 1 commit into
mainfrom
docs/static-diagram-links
Jul 15, 2026
Merged

docs: link post-it diagrams to API pages and adopt the generated triangle marker#623
DavidCozens merged 1 commit into
mainfrom
docs/static-diagram-links

Conversation

@DavidCozens

@DavidCozens DavidCozens commented Jul 15, 2026

Copy link
Copy Markdown
Collaborator

What

The committed post-it SVGs (architecture, storage, sl1sl3) predated the
generated relationship-diagram engine (S23.13) and had drifted from it. This brings the static hand-drawn diagrams back in line and makes them navigable, without changing their orientation.

Changes

  • Marker — replace the old chevron realises marker with the hollow triangle from postit-defs.svg, matching the generated diagrams.
  • Links — the green «interface» stickies, the SolidSyslog facade, and the Config sticky now link to their API compound pages via relative ../../api/… hrefs (27 links, all resolving to real pages). Backend/Null/injected stickies stay unlinked. Hover highlight is a darker shade of each sticky's own colour (green #6fae74, amber #b89a3c, rose #cf8a8a), matching the generated diagrams rather than the site-norm violet.
  • Embedding — the SL diagrams on security-levels.md switch from a Markdown image to <object> (with an <img> fallback for GitHub) so the SVG's internal links stay clickable; an <img>-loaded SVG swallows them. Relative link targets resolve within any deployment prefix, so versioned docs stay correct. Scoped MD033 exception with an inline reason.

Verification

  • All five SVGs parse as well-formed XML; markdownlint-cli2 (the CI gate) is clean.
  • Full mkdocs build succeeds; the rendered page emits <object data="../assets/postit/slN.svg"> with the path intact, the copied SVGs carry the links + new marker, and all target pages exist.
  • Reviewed live via mkdocs serve: interface/facade/config boxes highlight and click through to the right API pages.

Follows S23.13; part of E23 (#246).

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Updated security-level diagrams to render consistently in the documentation.
    • Preserved the existing diagrams and surrounding guidance.

…ngle marker

The committed post-it SVGs (architecture, storage, sl1-3) predated the generated
relationship-diagram engine (S23.13) and had drifted from it. Bring them back in
line and make them navigable.

- Replace the old chevron "realises" marker with the hollow triangle from
  postit-defs.svg, matching the generated diagrams.
- Link the green interface stickies, the SolidSyslog facade, and the Config
  sticky to their API compound pages via relative ../../api/... hrefs. Hover
  highlight is a darker shade of each sticky's own colour, as in the generated
  diagrams. Backend/Null/injected stickies stay unlinked.
- Embed the SL diagrams on security-levels.md via <object> (with an <img>
  fallback) so the SVG's internal links stay clickable; a Markdown image cannot
  carry them. Scoped MD033 exception with an inline reason.

Orientation left unchanged. Follows S23.13; part of E23.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Jul 15, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Walkthrough

The security-level documentation now embeds the existing SL1–SL3 SVG diagrams using HTML <object> elements with image fallbacks. An MD033 suppression is scoped around the HTML markup; descriptive guidance is unchanged.

Changes

Security-level documentation

Layer / File(s) Summary
Embed worked-combination diagrams
docs/security-levels.md
SL1–SL3 Markdown images now use HTML <object>/<img> embeds referencing the same SVG assets, with scoped MD033 lint suppression.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Possibly related PRs

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title is specific, Conventional Commits-formatted, and matches the main docs/SVG navigation changes.
Description check ✅ Passed The description covers purpose, change details, and verification; only the template headings differ from the repo’s preferred format.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/static-diagram-links

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 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/security-levels.md`:
- Line 67: Update the fallback img paths paired with the SVG object elements in
docs/security-levels.md at lines 67-67, 81-81, and 96-96 to use the same
../assets/... relative path as their matching object data attributes, preserving
each asset filename.
🪄 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: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 10ea6619-7c7a-437b-a7c0-c369d45ee50b

📥 Commits

Reviewing files that changed from the base of the PR and between 839e7b2 and ad8db0d.

⛔ Files ignored due to path filters (6)
  • docs/assets/postit/architecture.svg is excluded by !**/*.svg, !**/*.svg, !docs/assets/**
  • docs/assets/postit/sl1.svg is excluded by !**/*.svg, !**/*.svg, !docs/assets/**
  • docs/assets/postit/sl2.svg is excluded by !**/*.svg, !**/*.svg, !docs/assets/**
  • docs/assets/postit/sl3.svg is excluded by !**/*.svg, !**/*.svg, !docs/assets/**
  • docs/assets/postit/storage.svg is excluded by !**/*.svg, !**/*.svg, !docs/assets/**
  • docs/assets/stylesheets/brand.css is excluded by !docs/assets/**
📒 Files selected for processing (1)
  • docs/security-levels.md

Comment thread docs/security-levels.md
@github-actions

Copy link
Copy Markdown
Contributor

☀️   Quality Summary

   🚦   build-linux-gcc: 100% successful (✔️ 1522 passed)
   🚦   build-freertos-host-tdd-plustcp: 100% successful (✔️ 1873 passed)
   🚦   build-linux-clang: 100% successful (✔️ 1453 passed)
   🚦   sanitize-linux-gcc: 100% successful (✔️ 1453 passed)
   🚦   integration-linux-openssl: 100% successful (✔️ 16 passed)
   🚦   integration-linux-mbedtls: 100% successful (✔️ 14 passed)
   🚦   integration-windows-openssl: 100% successful (✔️ 16 passed)
   🚦   bdd-linux-syslog-ng: 94% successful (✔️ 49 passed, 🙈 3 skipped)
   🚦   bdd-windows-otel: 88% successful (✔️ 46 passed, 🙈 6 skipped)
   🚦   bdd-freertos-qemu-plustcp: 87% successful (✔️ 45 passed, 🙈 7 skipped)
   🚦   bdd-freertos-qemu-lwip: 87% successful (✔️ 45 passed, 🙈 7 skipped)
   🚦   build-windows-msvc: 100% successful (✔️ 1298 passed)
   🚦   build-linux-tunable-override: 100% successful (✔️ 1453 passed)
   ⚠️   Clang-Tidy: No warnings
   ⚠️   CPPCheck: No warnings


Created by Quality Monitor v1.14.0 (#f3859fd). More details are shown in the GitHub Checks Result.

@DavidCozens DavidCozens merged commit 7ba9f24 into main Jul 15, 2026
30 checks passed
@DavidCozens DavidCozens deleted the docs/static-diagram-links branch July 15, 2026 17:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant