Strip relatedResource tags from GitHub-rendered md files#21751
Strip relatedResource tags from GitHub-rendered md files#21751
Conversation
The {% relatedResource %} tags are custom Docusaurus/MDX markers meant
for the learn site. GitHub's markdown renderer shows them as raw text.
Add regex to clean_and_write() to strip these tags down to plain text
names, and regenerate all integration docs.
33b5c71 to
f906dca
Compare
There was a problem hiding this comment.
No issues found across 34 files
Confidence score: 5/5
- Automated review surfaced no issues in the provided summaries.
- No files require special attention.
Architecture diagram
sequenceDiagram
participant Script as gen_docs_integrations.py
participant Repo as Repository (.md files)
participant GitHub as GitHub Web UI
participant LearnSite as Learn Site (Docusaurus/MDX)
Note over Script,Repo: Documentation Generation Flow
Script->>Script: Generate Integration Metadata
rect rgb(23, 37, 84)
Note right of Script: CHANGED: clean_and_write()
Script->>Script: Convert {% details %} to HTML <details>
Script->>Script: NEW: Strip {% relatedResource %} tags via Regex
Script->>Script: NEW: Retain only inner plain-text name
end
Script->>Repo: Write cleaned Markdown to disk
Note over Repo,LearnSite: Runtime Rendering Flows
alt GitHub View
GitHub->>Repo: Fetch Markdown
GitHub->>GitHub: Render Standard Markdown
Note right of GitHub: Result: Related Resources show as plain text
else Learn Site Build
LearnSite->>Repo: Ingest Markdown via MDX Pipeline
Note over LearnSite: MDX handles remaining markers/logic
LearnSite-->>LearnSite: Render Interactive Links
end
Link k8s_state, k8s_apiserver, k8s_kubelet, k8s_kubeproxy, cgroups Kubernetes Containers, and CoreDNS as related resources so users can discover all K8s monitoring integrations from any one of them.
Replace plain-text related resource names with clickable markdown links pointing to the actual integration .md files in the repo. Uses a two-pass approach: write_to_file() records each integration's actual output path, then resolve_related_links() post-processes all files to convert relatedResource tags into [name](/path) links.
There was a problem hiding this comment.
15 issues found across 39 files (changes from recent commits).
Prompt for AI agents (all issues)
Check if these issues are valid — if so, understand the root cause of each and fix them.
<file name="src/collectors/ebpf.plugin/integrations/ebpf_shm.md">
<violation number="1" location="src/collectors/ebpf.plugin/integrations/ebpf_shm.md:39">
P2: The new link uses a leading `/`, which makes GitHub resolve it to the domain root instead of the repository, resulting in a broken link. Use a repo-relative path (no leading `/`).</violation>
</file>
<file name="src/collectors/ebpf.plugin/integrations/ebpf_oomkill.md">
<violation number="1" location="src/collectors/ebpf.plugin/integrations/ebpf_oomkill.md:39">
P2: These absolute "/src/..." links will be broken in GitHub-rendered Markdown because leading slashes resolve to the site root, not the repository. Use relative paths from this file so the links work within the repo.</violation>
</file>
<file name="src/collectors/ebpf.plugin/integrations/ebpf_cachestat.md">
<violation number="1" location="src/collectors/ebpf.plugin/integrations/ebpf_cachestat.md:39">
P2: Root-relative links (`/src/...`) will resolve to github.com/src/... and break in GitHub-rendered markdown. Use repository-relative paths instead so the links work inside this repo.</violation>
</file>
<file name="src/go/plugin/go.d/collector/rspamd/integrations/rspamd.md">
<violation number="1" location="src/go/plugin/go.d/collector/rspamd/integrations/rspamd.md:38">
P2: This absolute `/src/...` link will be broken on GitHub because leading-slash URLs resolve to `https://github.com/src/...` rather than the repo root. Use a repo-relative path from this file instead.</violation>
<violation number="2" location="src/go/plugin/go.d/collector/rspamd/integrations/rspamd.md:39">
P2: This absolute `/src/...` link will be broken on GitHub for the same reason; use a repo-relative link from this file instead.</violation>
</file>
<file name="src/collectors/ebpf.plugin/integrations/ebpf_swap.md">
<violation number="1" location="src/collectors/ebpf.plugin/integrations/ebpf_swap.md:39">
P2: This absolute link points to github.com/src/... instead of the file in this repo, so the GitHub-rendered link will 404. Use a relative path from this file’s directory (e.g., ../../apps.plugin/integrations/applications.md).</violation>
<violation number="2" location="src/collectors/ebpf.plugin/integrations/ebpf_swap.md:40">
P2: This absolute link points to github.com/src/... instead of the file in this repo, so the GitHub-rendered link will 404. Use a relative path from this file’s directory (e.g., ../../cgroups.plugin/integrations/containers.md).</violation>
</file>
<file name="src/collectors/ebpf.plugin/integrations/ebpf_vfs.md">
<violation number="1" location="src/collectors/ebpf.plugin/integrations/ebpf_vfs.md:39">
P2: This absolute link points to github.com/src/... rather than this repository on GitHub. Use a relative path so the link works in GitHub-rendered Markdown.</violation>
<violation number="2" location="src/collectors/ebpf.plugin/integrations/ebpf_vfs.md:40">
P2: This absolute link points to github.com/src/... rather than this repository on GitHub. Use a relative path so the link works in GitHub-rendered Markdown.</violation>
</file>
<file name="src/collectors/ebpf.plugin/integrations/ebpf_filedescriptor.md">
<violation number="1" location="src/collectors/ebpf.plugin/integrations/ebpf_filedescriptor.md:39">
P2: This absolute `/src/...` link will break on GitHub because it resolves to the domain root instead of the repo file. Use a relative link from this file’s directory.</violation>
<violation number="2" location="src/collectors/ebpf.plugin/integrations/ebpf_filedescriptor.md:40">
P2: This absolute `/src/...` link will break on GitHub because it resolves to the domain root instead of the repo file. Use a relative link from this file’s directory.</violation>
</file>
<file name="src/go/plugin/go.d/collector/coredns/integrations/coredns.md">
<violation number="1" location="src/go/plugin/go.d/collector/coredns/integrations/coredns.md:37">
P2: These links are root-relative, so GitHub resolves them to github.com/src/... instead of the netdata/netdata repo. Use repo-relative paths (../) or full GitHub URLs so the cross-links work in GitHub-rendered Markdown.</violation>
</file>
<file name="src/collectors/ebpf.plugin/integrations/ebpf_socket.md">
<violation number="1" location="src/collectors/ebpf.plugin/integrations/ebpf_socket.md:39">
P2: This absolute `/src/...` link will resolve to https://github.com/src/... on GitHub, so the cross-link is broken. Use a repo-relative path instead.</violation>
<violation number="2" location="src/collectors/ebpf.plugin/integrations/ebpf_socket.md:40">
P2: This absolute `/src/...` link will be broken on GitHub. Use a repo-relative path from this file instead.</violation>
</file>
<file name="integrations/gen_docs_integrations.py">
<violation number="1" location="integrations/gen_docs_integrations.py:72">
P2: The relatedResource replacement only matches inline tags; multiline tag bodies won’t be converted, leaving raw `{% relatedResource %}` blocks in the generated markdown. Consider matching across newlines.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
|
|
||
| - {% relatedResource id="apps.plugin-apps-Applications" %}Applications{% /relatedResource %} | ||
| - {% relatedResource id="cgroups.plugin-/sys/fs/cgroup-Containers" %}Containers{% /relatedResource %} | ||
| - [Applications](/src/collectors/apps.plugin/integrations/applications.md) |
There was a problem hiding this comment.
P2: The new link uses a leading /, which makes GitHub resolve it to the domain root instead of the repository, resulting in a broken link. Use a repo-relative path (no leading /).
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/collectors/ebpf.plugin/integrations/ebpf_shm.md, line 39:
<comment>The new link uses a leading `/`, which makes GitHub resolve it to the domain root instead of the repository, resulting in a broken link. Use a repo-relative path (no leading `/`).</comment>
<file context>
@@ -36,8 +36,8 @@ The plugin needs setuid because it loads data inside kernel. Netada sets necessa
-- Applications
-- Containers
+- [Applications](/src/collectors/apps.plugin/integrations/applications.md)
+- [Containers](/src/collectors/cgroups.plugin/integrations/containers.md)
</file context>
| - [Applications](/src/collectors/apps.plugin/integrations/applications.md) | |
| - [Applications](../../apps.plugin/integrations/applications.md) |
|
|
||
| - {% relatedResource id="apps.plugin-apps-Applications" %}Applications{% /relatedResource %} | ||
| - {% relatedResource id="cgroups.plugin-/sys/fs/cgroup-Containers" %}Containers{% /relatedResource %} | ||
| - [Applications](/src/collectors/apps.plugin/integrations/applications.md) |
There was a problem hiding this comment.
P2: These absolute "/src/..." links will be broken in GitHub-rendered Markdown because leading slashes resolve to the site root, not the repository. Use relative paths from this file so the links work within the repo.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/collectors/ebpf.plugin/integrations/ebpf_oomkill.md, line 39:
<comment>These absolute "/src/..." links will be broken in GitHub-rendered Markdown because leading slashes resolve to the site root, not the repository. Use relative paths from this file so the links work within the repo.</comment>
<file context>
@@ -36,8 +36,8 @@ The plugin needs setuid because it loads data inside kernel. Netada sets necessa
-- Applications
-- Containers
+- [Applications](/src/collectors/apps.plugin/integrations/applications.md)
+- [Containers](/src/collectors/cgroups.plugin/integrations/containers.md)
</file context>
| - [Applications](/src/collectors/apps.plugin/integrations/applications.md) | |
| - [Applications](../../apps.plugin/integrations/applications.md) |
|
|
||
| - {% relatedResource id="apps.plugin-apps-Applications" %}Applications{% /relatedResource %} | ||
| - {% relatedResource id="cgroups.plugin-/sys/fs/cgroup-Containers" %}Containers{% /relatedResource %} | ||
| - [Applications](/src/collectors/apps.plugin/integrations/applications.md) |
There was a problem hiding this comment.
P2: Root-relative links (/src/...) will resolve to github.com/src/... and break in GitHub-rendered markdown. Use repository-relative paths instead so the links work inside this repo.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/collectors/ebpf.plugin/integrations/ebpf_cachestat.md, line 39:
<comment>Root-relative links (`/src/...`) will resolve to github.com/src/... and break in GitHub-rendered markdown. Use repository-relative paths instead so the links work inside this repo.</comment>
<file context>
@@ -36,8 +36,8 @@ The plugin needs setuid because it loads data inside kernel. Netada sets necessa
-- Applications
-- Containers
+- [Applications](/src/collectors/apps.plugin/integrations/applications.md)
+- [Containers](/src/collectors/cgroups.plugin/integrations/containers.md)
</file context>
| - [Applications](/src/collectors/apps.plugin/integrations/applications.md) | |
| - [Applications](../../apps.plugin/integrations/applications.md) |
| - {% relatedResource id="go.d.plugin-httpcheck-HTTP_Endpoints" %}HTTP Endpoints{% /relatedResource %} | ||
| - {% relatedResource id="apps.plugin-apps-Applications" %}Applications{% /relatedResource %} | ||
| - [HTTP Endpoints](/src/go/plugin/go.d/collector/httpcheck/integrations/http_endpoints.md) | ||
| - [Applications](/src/collectors/apps.plugin/integrations/applications.md) |
There was a problem hiding this comment.
P2: This absolute /src/... link will be broken on GitHub for the same reason; use a repo-relative link from this file instead.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/go/plugin/go.d/collector/rspamd/integrations/rspamd.md, line 39:
<comment>This absolute `/src/...` link will be broken on GitHub for the same reason; use a repo-relative link from this file instead.</comment>
<file context>
@@ -35,8 +35,8 @@ This collector supports collecting metrics from multiple instances of this integ
-- HTTP Endpoints
-- Applications
+- [HTTP Endpoints](/src/go/plugin/go.d/collector/httpcheck/integrations/http_endpoints.md)
+- [Applications](/src/collectors/apps.plugin/integrations/applications.md)
### Default Behavior
</file context>
| - [Applications](/src/collectors/apps.plugin/integrations/applications.md) | |
| - [Applications](../../../../../../collectors/apps.plugin/integrations/applications.md) |
|
|
||
| - {% relatedResource id="go.d.plugin-httpcheck-HTTP_Endpoints" %}HTTP Endpoints{% /relatedResource %} | ||
| - {% relatedResource id="apps.plugin-apps-Applications" %}Applications{% /relatedResource %} | ||
| - [HTTP Endpoints](/src/go/plugin/go.d/collector/httpcheck/integrations/http_endpoints.md) |
There was a problem hiding this comment.
P2: This absolute /src/... link will be broken on GitHub because leading-slash URLs resolve to https://github.com/src/... rather than the repo root. Use a repo-relative path from this file instead.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/go/plugin/go.d/collector/rspamd/integrations/rspamd.md, line 38:
<comment>This absolute `/src/...` link will be broken on GitHub because leading-slash URLs resolve to `https://github.com/src/...` rather than the repo root. Use a repo-relative path from this file instead.</comment>
<file context>
@@ -35,8 +35,8 @@ This collector supports collecting metrics from multiple instances of this integ
-- HTTP Endpoints
-- Applications
+- [HTTP Endpoints](/src/go/plugin/go.d/collector/httpcheck/integrations/http_endpoints.md)
+- [Applications](/src/collectors/apps.plugin/integrations/applications.md)
</file context>
| - [HTTP Endpoints](/src/go/plugin/go.d/collector/httpcheck/integrations/http_endpoints.md) | |
| - [HTTP Endpoints](../../httpcheck/integrations/http_endpoints.md) |
|
|
||
| - {% relatedResource id="apps.plugin-apps-Applications" %}Applications{% /relatedResource %} | ||
| - {% relatedResource id="cgroups.plugin-/sys/fs/cgroup-Containers" %}Containers{% /relatedResource %} | ||
| - [Applications](/src/collectors/apps.plugin/integrations/applications.md) |
There was a problem hiding this comment.
P2: This absolute /src/... link will break on GitHub because it resolves to the domain root instead of the repo file. Use a relative link from this file’s directory.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/collectors/ebpf.plugin/integrations/ebpf_filedescriptor.md, line 39:
<comment>This absolute `/src/...` link will break on GitHub because it resolves to the domain root instead of the repo file. Use a relative link from this file’s directory.</comment>
<file context>
@@ -36,8 +36,8 @@ The plugin needs setuid because it loads data inside kernel. Netdata sets necess
-- Applications
-- Containers
+- [Applications](/src/collectors/apps.plugin/integrations/applications.md)
+- [Containers](/src/collectors/cgroups.plugin/integrations/containers.md)
</file context>
| - [Applications](/src/collectors/apps.plugin/integrations/applications.md) | |
| - [Applications](../../apps.plugin/integrations/applications.md) |
| - [Kubernetes Cluster State](/src/go/plugin/go.d/collector/k8s_state/integrations/kubernetes_cluster_state.md) | ||
| - [Kubernetes API Server](/src/go/plugin/go.d/collector/k8s_apiserver/integrations/kubernetes_api_server.md) | ||
| - [Kubelet](/src/go/plugin/go.d/collector/k8s_kubelet/integrations/kubelet.md) | ||
| - [Kubeproxy](/src/go/plugin/go.d/collector/k8s_kubeproxy/integrations/kubeproxy.md) | ||
| - [Kubernetes Containers](/src/collectors/cgroups.plugin/integrations/kubernetes_containers.md) |
There was a problem hiding this comment.
P2: These links are root-relative, so GitHub resolves them to github.com/src/... instead of the netdata/netdata repo. Use repo-relative paths (../) or full GitHub URLs so the cross-links work in GitHub-rendered Markdown.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/go/plugin/go.d/collector/coredns/integrations/coredns.md, line 37:
<comment>These links are root-relative, so GitHub resolves them to github.com/src/... instead of the netdata/netdata repo. Use repo-relative paths (../) or full GitHub URLs so the cross-links work in GitHub-rendered Markdown.</comment>
<file context>
@@ -34,11 +34,11 @@ This collector supports collecting metrics from multiple instances of this integ
-- Kubelet
-- Kubeproxy
-- Kubernetes Containers
+- [Kubernetes Cluster State](/src/go/plugin/go.d/collector/k8s_state/integrations/kubernetes_cluster_state.md)
+- [Kubernetes API Server](/src/go/plugin/go.d/collector/k8s_apiserver/integrations/kubernetes_api_server.md)
+- [Kubelet](/src/go/plugin/go.d/collector/k8s_kubelet/integrations/kubelet.md)
</file context>
| - [Kubernetes Cluster State](/src/go/plugin/go.d/collector/k8s_state/integrations/kubernetes_cluster_state.md) | |
| - [Kubernetes API Server](/src/go/plugin/go.d/collector/k8s_apiserver/integrations/kubernetes_api_server.md) | |
| - [Kubelet](/src/go/plugin/go.d/collector/k8s_kubelet/integrations/kubelet.md) | |
| - [Kubeproxy](/src/go/plugin/go.d/collector/k8s_kubeproxy/integrations/kubeproxy.md) | |
| - [Kubernetes Containers](/src/collectors/cgroups.plugin/integrations/kubernetes_containers.md) | |
| - [Kubernetes Cluster State](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/k8s_state/integrations/kubernetes_cluster_state.md) | |
| - [Kubernetes API Server](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/k8s_apiserver/integrations/kubernetes_api_server.md) | |
| - [Kubelet](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/k8s_kubelet/integrations/kubelet.md) | |
| - [Kubeproxy](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/k8s_kubeproxy/integrations/kubeproxy.md) | |
| - [Kubernetes Containers](https://github.com/netdata/netdata/blob/master/src/collectors/cgroups.plugin/integrations/kubernetes_containers.md) |
| - {% relatedResource id="apps.plugin-apps-Applications" %}Applications{% /relatedResource %} | ||
| - {% relatedResource id="cgroups.plugin-/sys/fs/cgroup-Containers" %}Containers{% /relatedResource %} | ||
| - [Applications](/src/collectors/apps.plugin/integrations/applications.md) | ||
| - [Containers](/src/collectors/cgroups.plugin/integrations/containers.md) |
There was a problem hiding this comment.
P2: This absolute /src/... link will be broken on GitHub. Use a repo-relative path from this file instead.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/collectors/ebpf.plugin/integrations/ebpf_socket.md, line 40:
<comment>This absolute `/src/...` link will be broken on GitHub. Use a repo-relative path from this file instead.</comment>
<file context>
@@ -36,8 +36,8 @@ The plugin needs setuid because it loads data inside kernel. Netada sets necessa
-- Applications
-- Containers
+- [Applications](/src/collectors/apps.plugin/integrations/applications.md)
+- [Containers](/src/collectors/cgroups.plugin/integrations/containers.md)
### Default Behavior
</file context>
| - [Containers](/src/collectors/cgroups.plugin/integrations/containers.md) | |
| - [Containers](../../cgroups.plugin/integrations/containers.md) |
|
|
||
| - {% relatedResource id="apps.plugin-apps-Applications" %}Applications{% /relatedResource %} | ||
| - {% relatedResource id="cgroups.plugin-/sys/fs/cgroup-Containers" %}Containers{% /relatedResource %} | ||
| - [Applications](/src/collectors/apps.plugin/integrations/applications.md) |
There was a problem hiding this comment.
P2: This absolute /src/... link will resolve to https://github.com/src/... on GitHub, so the cross-link is broken. Use a repo-relative path instead.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/collectors/ebpf.plugin/integrations/ebpf_socket.md, line 39:
<comment>This absolute `/src/...` link will resolve to https://github.com/src/... on GitHub, so the cross-link is broken. Use a repo-relative path instead.</comment>
<file context>
@@ -36,8 +36,8 @@ The plugin needs setuid because it loads data inside kernel. Netada sets necessa
-- Applications
-- Containers
+- [Applications](/src/collectors/apps.plugin/integrations/applications.md)
+- [Containers](/src/collectors/cgroups.plugin/integrations/containers.md)
</file context>
| - [Applications](/src/collectors/apps.plugin/integrations/applications.md) | |
| - [Applications](../../apps.plugin/integrations/applications.md) |
| return f'[{name}](/{target})' | ||
| return name | ||
|
|
||
| md = re.sub(r'\{% relatedResource id="([^"]*)" %\}(.*?)\{% /relatedResource %\}', _resolve, md) |
There was a problem hiding this comment.
P2: The relatedResource replacement only matches inline tags; multiline tag bodies won’t be converted, leaving raw {% relatedResource %} blocks in the generated markdown. Consider matching across newlines.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At integrations/gen_docs_integrations.py, line 72:
<comment>The relatedResource replacement only matches inline tags; multiline tag bodies won’t be converted, leaving raw `{% relatedResource %}` blocks in the generated markdown. Consider matching across newlines.</comment>
<file context>
@@ -36,15 +39,40 @@ def cleanup(only_base_paths=None):
+ return f'[{name}](/{target})'
+ return name
+
+ md = re.sub(r'\{% relatedResource id="([^"]*)" %\}(.*?)\{% /relatedResource %\}', _resolve, md)
+ p.write_text(md, encoding="utf-8")
+
</file context>
| md = re.sub(r'\{% relatedResource id="([^"]*)" %\}(.*?)\{% /relatedResource %\}', _resolve, md) | |
| md = re.sub(r'\{% relatedResource id="([^"]*)" %\}([\s\S]*?)\{% /relatedResource %\}', _resolve, md) |
Summary
{% relatedResource %}tags are custom Docusaurus/MDX markers processed by the learn site. GitHub's markdown renderer doesn't understand them and shows raw template code (e.g.{% relatedResource id="..." %}Name{% /relatedResource %}).clean_and_write()ingen_docs_integrations.pyto strip these tags to plain text names in the repo.mdfiles.Test plan
{% relatedResource %}tagsSummary by cubic
Converted custom relatedResource tags in generated Markdown into clickable links so GitHub shows clean cross-links. Also added cross-links across Kubernetes integrations and between Nvidia GPU and NVIDIA DCGM Exporter.
Bug Fixes
New Features
Written for commit bfed902. Summary will update on new commits.