Skip to content

Commit 00815ba

Browse files
mmanciopmmanciop
committed
chore: add Markdown viewer for pages
1 parent 517bccf commit 00815ba

File tree

10 files changed

+348
-8
lines changed

10 files changed

+348
-8
lines changed

‎.github/workflows/release.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ jobs:
3131
uses: open-telemetry/weaver/.github/actions/setup-weaver@6efae3022af925deab04aa70924cd501443fb7f9 # v0.21.2
3232

3333
- name: Generate registry documentation
34-
run: weaver registry generate --registry=./model --templates=./templates markdown ./docs/
34+
run: ./scripts/generate-docs.sh
3535

3636
- name: Configure Pages
3737
uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0

‎.github/workflows/validate-pr.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ jobs:
9696
uses: open-telemetry/weaver/.github/actions/setup-weaver@6efae3022af925deab04aa70924cd501443fb7f9 # v0.21.2
9797

9898
- name: Generate registry documentation
99-
run: weaver registry generate --registry=./model --templates=./templates markdown ./docs/
99+
run: ./scripts/generate-docs.sh
100100

101101
- name: Upload documentation artifact
102102
uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0

‎assets/dash0-logo.svg‎

Lines changed: 3 additions & 0 deletions
Loading

‎scripts/generate-docs.sh‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
#!/usr/bin/env bash
2+
# SPDX-FileCopyrightText: Copyright 2026 Dash0 Inc.
3+
#
4+
# Generate the semantic conventions documentation.
5+
# Works both locally (via Docker) and in CI (with Weaver installed).
6+
7+
set -euo pipefail
8+
9+
REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
10+
OUTPUT_DIR="${1:-${REPO_ROOT}/docs}"
11+
12+
if command -v weaver &>/dev/null; then
13+
echo "Using local Weaver installation"
14+
weaver registry generate \
15+
--registry="${REPO_ROOT}/model" \
16+
--templates="${REPO_ROOT}/templates" \
17+
markdown \
18+
"${OUTPUT_DIR}"
19+
else
20+
echo "Weaver not found, using Docker"
21+
docker run --rm \
22+
-v "${REPO_ROOT}/model:/model" \
23+
-v "${REPO_ROOT}/templates:/templates" \
24+
-v "${OUTPUT_DIR}:/docs" \
25+
otel/weaver:latest \
26+
registry generate \
27+
--registry=/model \
28+
--templates=/templates \
29+
markdown \
30+
/docs/
31+
fi
32+
33+
echo "Documentation generated in ${OUTPUT_DIR}"

‎templates/registry/markdown/attribute_macros.j2‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818

1919
{% macro find_lineage(attr_id, lineage) %}{% if attr_id in lineage %}{{lineage[attr_id].source_group}}{% endif %}{% endmacro %}
2020

21-
{% macro name_with_link(attribute, attribute_registry_base_url, lineage_attributes) %}[`{{name(attribute)}}`]({{attribute_registry_base_url}}/{{ find_lineage(attribute.name, lineage_attributes) | split_id | list | reject("eq", "registry")| first | kebab_case }}.md){% endmacro %}
21+
{% macro name_with_link(attribute, attribute_registry_base_url, lineage_attributes) %}`{{name(attribute)}}`{% endmacro %}
2222

2323
{% macro display_name(group) %}
2424
{%- if 'display_name' in group %}{{ group.display_name }}

‎templates/registry/markdown/entity_macros.j2‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -51,9 +51,9 @@
5151

5252
| Role | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
5353
| --- | --- | --- | --- | --- | --- | --- |{%- if id_attrs | length > 0 %}
54-
{{ attribute_table(id_attrs, "/docs/registry/attributes", e.lineage.attributes, notes, "identity") | trim }}{% endif %}{%- if desc_attrs | length > 0 %}
55-
{{ attribute_table(desc_attrs, "/docs/registry/attributes", e.lineage.attributes, notes, "description") | trim }}{% endif %}{%- if misc_attrs | length > 0 %}
56-
{{ attribute_table(misc_attrs, "/docs/registry/attributes", e.lineage.attributes, notes, "other") | trim }}{% endif %}
54+
{{ attribute_table(id_attrs, "https://opentelemetry.io/docs/specs/semconv/attributes-registry", e.lineage.attributes, notes, "identity") | trim }}{% endif %}{%- if desc_attrs | length > 0 %}
55+
{{ attribute_table(desc_attrs, "https://opentelemetry.io/docs/specs/semconv/attributes-registry", e.lineage.attributes, notes, "description") | trim }}{% endif %}{%- if misc_attrs | length > 0 %}
56+
{{ attribute_table(misc_attrs, "https://opentelemetry.io/docs/specs/semconv/attributes-registry", e.lineage.attributes, notes, "other") | trim }}{% endif %}
5757

5858
{{ notes.render() | trim }}
5959

‎templates/registry/markdown/event_namespace.md.j2‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,6 @@
99

1010
{{ event.header(e) | trim }}
1111

12-
{{ at.generate(e.attributes, [], "/docs/registry/attributes", e.lineage.attributes) }}
12+
{{ at.generate(e.attributes, [], "https://opentelemetry.io/docs/specs/semconv/attributes-registry", e.lineage.attributes) }}
1313
{{ event.body(e.body) }}
1414
{% endfor %}

‎templates/registry/markdown/index.html.j2‎

Lines changed: 294 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,294 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1">
6+
<title>Dash0 Semantic Conventions</title>
7+
<style>
8+
:root {
9+
--bg: #111111;
10+
--bg-surface: #1a1a1a;
11+
--bg-elevated: #212121;
12+
--fg: #ffffff;
13+
--fg-secondary: #969696;
14+
--fg-muted: #757575;
15+
--border: #2c2c2c;
16+
--border-subtle: #222222;
17+
--link: #e8875b;
18+
--link-hover: #f4a47a;
19+
--code-bg: #1a1a1a;
20+
--code-border: #2c2c2c;
21+
--nav-bg: #141414;
22+
--nav-active: #1e1e1e;
23+
--nav-hover: #1a1a1a;
24+
--table-header: #1a1a1a;
25+
--table-stripe: #151515;
26+
--accent: #e8875b;
27+
--accent-dim: rgba(232, 135, 91, 0.15);
28+
--radius: 8px;
29+
--radius-sm: 4px;
30+
}
31+
* { box-sizing: border-box; margin: 0; padding: 0; }
32+
body {
33+
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
34+
background: var(--bg);
35+
color: var(--fg);
36+
display: flex;
37+
min-height: 100vh;
38+
font-size: 15px;
39+
line-height: 1.6;
40+
-webkit-font-smoothing: antialiased;
41+
}
42+
43+
/* Sidebar */
44+
nav {
45+
width: 260px;
46+
min-width: 260px;
47+
background: var(--nav-bg);
48+
border-right: 1px solid var(--border-subtle);
49+
padding: 0;
50+
overflow-y: auto;
51+
position: sticky;
52+
top: 0;
53+
height: 100vh;
54+
}
55+
nav .logo {
56+
padding: 1.25rem 1.25rem 1rem;
57+
font-weight: 600;
58+
font-size: 0.95rem;
59+
letter-spacing: 0.02em;
60+
border-bottom: 1px solid var(--border-subtle);
61+
display: flex;
62+
align-items: baseline;
63+
gap: 0.6rem;
64+
}
65+
nav .logo svg {
66+
height: 16px;
67+
width: auto;
68+
flex-shrink: 0;
69+
}
70+
nav .section-title {
71+
padding: 1rem 1.25rem 0.35rem;
72+
font-size: 0.65rem;
73+
font-weight: 600;
74+
text-transform: uppercase;
75+
letter-spacing: 0.1em;
76+
color: var(--fg-muted);
77+
}
78+
nav a {
79+
display: block;
80+
padding: 0.35rem 1.25rem 0.35rem 1.75rem;
81+
color: var(--fg-secondary);
82+
text-decoration: none;
83+
font-size: 0.82rem;
84+
border-left: 2px solid transparent;
85+
transition: all 0.15s ease;
86+
}
87+
nav a:hover {
88+
color: var(--fg);
89+
background: var(--nav-hover);
90+
}
91+
nav a.active {
92+
color: var(--fg);
93+
background: var(--nav-active);
94+
border-left-color: var(--accent);
95+
}
96+
97+
/* Main content */
98+
main {
99+
flex: 1;
100+
max-width: 920px;
101+
padding: 2.5rem 3.5rem;
102+
overflow-x: auto;
103+
}
104+
main h1 {
105+
font-size: 1.75rem;
106+
font-weight: 600;
107+
margin-bottom: 1.25rem;
108+
letter-spacing: -0.01em;
109+
}
110+
main h2 {
111+
font-size: 1.25rem;
112+
font-weight: 600;
113+
margin-top: 2.25rem;
114+
margin-bottom: 0.75rem;
115+
padding-bottom: 0.5rem;
116+
border-bottom: 1px solid var(--border-subtle);
117+
letter-spacing: -0.01em;
118+
}
119+
main h3 {
120+
font-size: 1.05rem;
121+
font-weight: 600;
122+
margin-top: 1.75rem;
123+
margin-bottom: 0.5rem;
124+
}
125+
main p {
126+
margin: 0.6rem 0;
127+
color: var(--fg-secondary);
128+
line-height: 1.7;
129+
}
130+
main a { color: var(--link); text-decoration: none; transition: color 0.15s; }
131+
main a:hover { color: var(--link-hover); }
132+
133+
/* Code */
134+
main code {
135+
background: var(--code-bg);
136+
border: 1px solid var(--code-border);
137+
padding: 0.15rem 0.4rem;
138+
border-radius: var(--radius-sm);
139+
font-family: "SF Mono", "Fira Code", "Fira Mono", Menlo, Consolas, monospace;
140+
font-size: 0.82em;
141+
color: var(--accent);
142+
}
143+
main pre {
144+
background: var(--code-bg);
145+
border: 1px solid var(--code-border);
146+
padding: 1rem 1.25rem;
147+
border-radius: var(--radius);
148+
overflow-x: auto;
149+
margin: 1rem 0;
150+
}
151+
main pre code {
152+
background: none;
153+
border: none;
154+
padding: 0;
155+
color: var(--fg-secondary);
156+
}
157+
158+
/* Tables */
159+
main table {
160+
border-collapse: separate;
161+
border-spacing: 0;
162+
width: 100%;
163+
margin: 1rem 0;
164+
font-size: 0.84rem;
165+
border: 1px solid var(--border);
166+
border-radius: var(--radius);
167+
overflow: hidden;
168+
}
169+
main th {
170+
background: var(--table-header);
171+
text-align: left;
172+
padding: 0.6rem 0.85rem;
173+
font-weight: 600;
174+
font-size: 0.75rem;
175+
text-transform: uppercase;
176+
letter-spacing: 0.04em;
177+
color: var(--fg-muted);
178+
border-bottom: 1px solid var(--border);
179+
}
180+
main td {
181+
padding: 0.55rem 0.85rem;
182+
border-bottom: 1px solid var(--border-subtle);
183+
color: var(--fg-secondary);
184+
}
185+
main tr:last-child td { border-bottom: none; }
186+
main tr:nth-child(even) { background: var(--table-stripe); }
187+
main tr:hover td { background: var(--nav-active); }
188+
189+
/* Blockquotes / callouts */
190+
main blockquote {
191+
border-left: 3px solid var(--accent);
192+
background: var(--accent-dim);
193+
padding: 0.75rem 1rem;
194+
margin: 1rem 0;
195+
border-radius: 0 var(--radius-sm) var(--radius-sm) 0;
196+
color: var(--fg-secondary);
197+
}
198+
199+
/* Lists */
200+
main ul, main ol { margin: 0.6rem 0 0.6rem 1.5rem; color: var(--fg-secondary); }
201+
main li { margin: 0.3rem 0; line-height: 1.7; }
202+
main li code { font-size: 0.8em; }
203+
204+
/* Badges */
205+
main img[src*="badge"] { vertical-align: middle; border-radius: 3px; }
206+
207+
/* Strong */
208+
main strong { color: var(--fg); font-weight: 600; }
209+
210+
/* Loading */
211+
#loading { color: var(--fg-muted); font-style: italic; }
212+
213+
/* Responsive */
214+
@media (max-width: 768px) {
215+
body { flex-direction: column; }
216+
nav {
217+
width: 100%;
218+
min-width: 100%;
219+
height: auto;
220+
position: static;
221+
border-right: none;
222+
border-bottom: 1px solid var(--border-subtle);
223+
}
224+
main { padding: 1.5rem 1.25rem; }
225+
}
226+
</style>
227+
</head>
228+
<body>
229+
<nav id="sidebar">
230+
<div class="logo"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 105 20" height="20" width="105"><path fill="white" d="M7.04688 16.9685C5.17773 18.8328 2.64258 19.8799 0 19.8799V0C2.64258 0 5.17773 1.04736 7.04688 2.91138C8.91602 4.77539 9.96484 7.30371 9.96484 9.93994C9.96484 12.5762 8.91602 15.1045 7.04688 16.9685ZM38.6367 12.8672C38.6367 17.092 41.084 20 45.2383 20C46.916 20 48.4551 19.2593 49.2539 18.0522V19.7805H52.6094V0.027832H49.2539V7.6272C48.4551 6.50244 46.998 5.73413 45.1836 5.73413C41.084 5.73413 38.6367 8.64209 38.6367 12.8672ZM49.4727 12.8672C49.4727 15.4185 47.9883 17.092 45.7324 17.092C43.4766 17.092 41.9922 15.4185 41.9922 12.8672C41.9922 10.3157 43.4766 8.64209 45.7324 8.64209C47.9883 8.64209 49.4727 10.3157 49.4727 12.8672ZM59.2539 5.73413C62.7754 5.73413 65.25 7.7644 65.25 10.8918V15.1716H68.2051C68.3418 16.4885 69.3594 17.3115 70.8711 17.3115C71.5762 17.3115 72.1562 17.1238 72.543 16.8232C72.8809 16.5613 73.0723 16.2136 73.0723 15.8301C73.0723 14.5386 71.7305 14.3086 70.1758 14.042C68.0312 13.6741 65.4805 13.2366 65.4805 9.84937C65.4805 7.43506 67.5996 5.73413 70.459 5.73413C73.7051 5.73413 75.9316 7.51733 76.0703 10.2061H72.9902C72.7969 8.9165 71.6152 8.25806 70.541 8.25806C70.2051 8.25806 69.9004 8.30078 69.6348 8.38232C69.4102 8.45166 69.2148 8.54932 69.0527 8.67285C68.7207 8.92578 68.5332 9.2876 68.5332 9.7395C68.5332 10.9619 69.8203 11.1345 71.3418 11.3386C73.543 11.6338 76.2344 11.9949 76.2344 15.6929C76.2344 18.2991 74.1172 20 70.8711 20C67.8828 20 65.7891 18.5198 65.25 16.1023V19.7805H61.9219V17.7229C61.3457 19.0947 59.75 20 57.7695 20C55.0195 20 53.1484 18.2441 53.1484 15.8574C53.1484 13.1689 55.2402 11.4954 58.3477 11.4954H60.9043C61.5918 11.4954 61.9219 11.1113 61.9219 10.5625C61.9219 10.4824 61.918 10.4038 61.9102 10.3267C61.9043 10.2534 61.8945 10.1814 61.8809 10.1108C61.8574 9.99316 61.8262 9.87964 61.7852 9.77051L61.7676 9.72168L61.6816 9.5332L61.6484 9.47266L61.5762 9.35596C61.1328 8.67993 60.2754 8.25806 59.0898 8.25806C57.3027 8.25806 56.2285 9.38281 56.1738 10.6174H53.1484C53.3145 7.87402 55.6523 5.73413 59.2539 5.73413ZM58.5664 17.5034C60.6855 17.5034 61.9219 16.022 61.9219 13.937V13.7175H58.8145C58.0859 13.7175 57.4785 13.9243 57.0586 14.2869C56.6543 14.6355 56.4219 15.1284 56.4219 15.7202C56.4219 16.7903 57.3027 17.5034 58.5664 17.5034ZM76.5898 19.7805V0.027832H79.9453V8.09351C80.7148 6.58472 82.3105 5.73413 84.291 5.73413C87.3984 5.73413 89.4336 7.98389 89.4336 11.2209V19.7805H86.0781V11.9343C86.0781 10.0413 84.8965 8.72461 83.1621 8.72461C81.293 8.72461 79.9453 10.2061 79.9453 12.2361V19.7805H76.5898ZM89.9551 10.8369C89.9551 16.7078 92.1289 20 96.9141 20H98.0137C102.799 20 105 16.7078 105 10.8369V9.52002C105 3.64917 102.799 0.356934 98.0137 0.356934H96.9141C92.1289 0.356934 89.9551 3.64917 89.9551 9.52002V10.8369ZM97.8496 16.845H97.0781C94.9062 16.845 93.5859 15.1716 93.5859 11.7971V8.55981C93.5859 5.15796 94.9062 3.48462 97.0781 3.48462H97.8496C100.021 3.48462 101.369 5.15796 101.369 8.55981V11.7971C101.369 15.1716 100.021 16.845 97.8496 16.845ZM20.5 20C26.0234 20 30.5 15.5229 30.5 10C30.5 4.47705 26.0234 0 20.5 0C14.9766 0 10.5 4.47705 10.5 10C10.5 15.5229 14.9766 20 20.5 20Z" clip-rule="evenodd" fill-rule="evenodd"></path></svg> SemConvs</div>
231+
<a href="#README.md">Overview</a>
232+
<div class="section-title">Attributes</div>
233+
<a href="#attributes/README.md">Overview</a>
234+
{%- for bundle in ctx.attribute_bundles %}
235+
<a href="#attributes/{{ bundle.id | kebab_case }}.md">{{ bundle.id | title_case | acronym }}</a>
236+
{%- endfor %}
237+
<div class="section-title">Entities</div>
238+
<a href="#entities/README.md">Overview</a>
239+
{%- for bundle in ctx.entity_bundles %}
240+
<a href="#entities/{{ bundle.id | kebab_case }}.md">{{ bundle.id | title_case | acronym }}</a>
241+
{%- endfor %}
242+
<div class="section-title">Events</div>
243+
<a href="#events/README.md">Overview</a>
244+
{%- for bundle in ctx.event_bundles %}
245+
<a href="#events/{{ bundle.id | kebab_case }}.md">{{ bundle.id | title_case | acronym }}</a>
246+
{%- endfor %}
247+
<div class="section-title">Metrics</div>
248+
<a href="#metrics/README.md">Overview</a>
249+
{%- for bundle in ctx.metric_bundles %}
250+
<a href="#metrics/{{ bundle.id | kebab_case }}.md">{{ bundle.id | title_case | acronym }}</a>
251+
{%- endfor %}
252+
</nav>
253+
<main>
254+
<div id="content"><p id="loading">Loading...</p></div>
255+
</main>
256+
<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
257+
<script>
258+
(function() {
259+
const content = document.getElementById('content');
260+
261+
function loadPage(path) {
262+
fetch(path)
263+
.then(r => { if (!r.ok) throw new Error(r.status); return r.text(); })
264+
.then(md => {
265+
content.innerHTML = marked.parse(md);
266+
// Rewrite .md links to hash links
267+
content.querySelectorAll('a[href]').forEach(a => {
268+
const href = a.getAttribute('href');
269+
if (href && href.endsWith('.md') && !href.startsWith('http')) {
270+
const base = path.substring(0, path.lastIndexOf('/') + 1);
271+
const resolved = new URL(href, location.origin + '/' + base).pathname.replace(/^\//, '');
272+
a.setAttribute('href', '#' + resolved);
273+
}
274+
});
275+
// Update active nav link
276+
document.querySelectorAll('nav a').forEach(a => {
277+
a.classList.toggle('active', a.getAttribute('href') === '#' + path);
278+
});
279+
window.scrollTo(0, 0);
280+
})
281+
.catch(() => { content.innerHTML = '<p>Page not found.</p>'; });
282+
}
283+
284+
function onHashChange() {
285+
const path = location.hash.slice(1) || 'README.md';
286+
loadPage(path);
287+
}
288+
289+
window.addEventListener('hashchange', onHashChange);
290+
onHashChange();
291+
})();
292+
</script>
293+
</body>
294+
</html>

‎templates/registry/markdown/metric_namespace.md.j2‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,6 @@
2929
{{ group.note }}
3030
{%- endif %}
3131
{%- if group.attributes %}
32-
{{ at.generate(group.attributes, [], "/docs/registry/attributes", group.lineage.attributes) }}
32+
{{ at.generate(group.attributes, [], "https://opentelemetry.io/docs/specs/semconv/attributes-registry", group.lineage.attributes) }}
3333
{%- endif %}
3434
{% endfor %}

0 commit comments

Comments
 (0)