chore: fix rendering of GitHub-like notes

Author: mmanciop

CONTRIBUTING.md

@@ -59,6 +59,21 @@ make test-valid
 make test-invalid
 ```
 
+## Previewing the documentation site
+
+Generate the documentation from the model and templates, then serve it locally:
+
+```sh
+make serve-docs
+```
+
+This regenerates the Markdown files in `docs/` and starts a local server at `http://localhost:8000`.
+To regenerate without serving:
+
+```sh
+make generate-docs
+```
+
 ## Pull requests
 
 All pull requests are validated in CI, which runs:

Makefile

@@ -1,4 +1,4 @@
-.PHONY: check resolve test test-valid test-invalid
+.PHONY: check resolve test test-valid test-invalid generate-docs serve-docs
 
 ## Validate the registry model.
 check:
@@ -18,3 +18,12 @@ test-valid:
 ## Run invalid live-check tests (each file must be rejected).
 test-invalid:
 	@.github/scripts/run-live-check-tests.sh invalid
+
+## Generate the documentation site from the model and templates.
+generate-docs:
+	@scripts/generate-docs.sh
+
+## Serve the documentation site locally on port 8000.
+serve-docs: generate-docs
+	@echo "Serving docs at http://localhost:8000"
+	@cd docs && python3 -m http.server 8000

templates/registry/markdown/index.html.j2

@@ -216,6 +216,53 @@
     color: var(--fg-secondary);
   }
 
+  /* GitHub-style alerts (via marked-alert) */
+  main .markdown-alert {
+    border-left: 3px solid;
+    padding: 0.75rem 1rem;
+    margin: 1rem 0;
+    border-radius: 0 var(--radius-sm) var(--radius-sm) 0;
+    color: var(--fg-secondary);
+  }
+  main .markdown-alert .markdown-alert-title {
+    display: flex;
+    align-items: center;
+    gap: 0.4rem;
+    font-weight: 600;
+    margin-bottom: 0.25rem;
+  }
+  main .markdown-alert .markdown-alert-title svg {
+    width: 16px;
+    height: 16px;
+    flex-shrink: 0;
+    fill: currentColor;
+  }
+  main .markdown-alert-note {
+    border-left-color: #478be6;
+    background: rgba(71, 139, 230, 0.1);
+  }
+  main .markdown-alert-note .markdown-alert-title { color: #478be6; }
+  main .markdown-alert-tip {
+    border-left-color: #3fb950;
+    background: rgba(63, 185, 80, 0.1);
+  }
+  main .markdown-alert-tip .markdown-alert-title { color: #3fb950; }
+  main .markdown-alert-important {
+    border-left-color: #a371f7;
+    background: rgba(163, 113, 247, 0.1);
+  }
+  main .markdown-alert-important .markdown-alert-title { color: #a371f7; }
+  main .markdown-alert-warning {
+    border-left-color: #d29922;
+    background: rgba(210, 153, 34, 0.1);
+  }
+  main .markdown-alert-warning .markdown-alert-title { color: #d29922; }
+  main .markdown-alert-caution {
+    border-left-color: #f85149;
+    background: rgba(248, 81, 73, 0.1);
+  }
+  main .markdown-alert-caution .markdown-alert-title { color: #f85149; }
+
   /* Lists */
   main ul, main ol { margin: 0.6rem 0 0.6rem 1.5rem; color: var(--fg-secondary); }
   main li { margin: 0.3rem 0; line-height: 1.7; }
@@ -274,7 +321,9 @@
   <div id="content"><p id="loading">Loading...</p></div>
 </main>
 <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/marked-alert/dist/index.umd.js"></script>
 <script>
+marked.use(markedAlert());
 (function() {
   const content = document.getElementById('content');