A component's graph in TechDocs
A component’s docs page can carry its graph. Backstage TechDocs builds the page with MkDocs and sanitizes the HTML before it draws it, so what survives depends on how the instance is set up. This page gives two ways in: an image that works on an unchanged instance, and a live frame of the hosted export that needs one admin change.
Both were checked in a local TechDocs preview built with techdocs-cli serve (CLI 1.14.1, mkdocs-techdocs-core) for a sample component. The live frame was checked again in a scratch Backstage app (1.56.0, new frontend system, TechDocs built by the backend with the local builder) driven by headless Chrome: with the host in allowedIframeHosts the page drew the frame, and with the line removed the page had no iframe at all. The sanitizer and publisher behaviour below is read from the Backstage source and docs.
What TechDocs lets through
Section titled “What TechDocs lets through”- TechDocs runs the page through DOMPurify. It strips
scriptand forbidsstyle. - An
iframeis removed unlesstechdocs.sanitizer.allowedIframeHostsis set and the host of itssrcis in the list. The match is exact against the URL’s host, so a port is part of it (localhost:8081, notlocalhost). - The TechDocs publisher serves any file whose extension contains
htm,xmlorsvgastext/plain. Agraph.svgkept beside the page therefore does not draw in an<img>, and the export cannot be served from TechDocs itself. It has to be hosted elsewhere. - The Backstage backend sets a content security policy when it serves the app. Its defaults are
img-src 'self' data:, and noframe-src, which falls back todefault-src 'self'. A production instance can refuse an image or a frame from another host untilbackend.csplists it. Thetechdocs-clipreview app does not apply that policy, so a page that renders there still needs the check on your own instance.
Without changing Backstage: an image
Section titled “Without changing Backstage: an image”Write the component’s cut as a static SVG with behold graph --svg, turn it into a PNG, and keep the PNG in the component’s docs/ folder. MkDocs copies it into the site, TechDocs serves .png with the right type, and the image is on the same origin as the page.
npx @intentius/behold graph . --around prod/prod/aws_s3_bucket.artifacts --depth 2 \ --svg --theme light -o graph.svgrsvg-convert -w 1400 graph.svg -o docs/graph/artifacts.png--around takes the ids of the cards to centre on (see the graph document for the ids, or read them from graph.json), and --depth is how many hops to keep. Leave --around off for the whole graph. Then in docs/index.md:
A graph small enough to embed can skip the file: put the SVG in the page as a data: URI, which DOMPurify keeps on an img and which the default img-src allows.
The picture is as fresh as the last time the command ran, so run it in the component’s own CI before the docs build, or commit the file with the change it draws.
With one admin line: a live frame
Section titled “With one admin line: a live frame”Publish the export with the Pages workflow (or any static host), then allow its host in the Backstage app-config.yaml:
techdocs: sanitizer: allowedIframeHosts: - OWNER.github.ioOn an instance that sets backend.csp, add the same host to frame-src (and keep 'self' in it):
backend: csp: frame-src: ["'self'", 'https://OWNER.github.io']Then put the frame in the page:
<iframe src="https://OWNER.github.io/REPO/?embed=1&bare=1&theme=light&member=prod" title="artifacts-service graph" width="100%" height="520" style="border:1px solid #ccc" loading="lazy"></iframe>The view parameters are the ones the export already reads:
embed=1&bare=1draws the graph alone, with no side panel, inspect pane or buttons.theme=lightortheme=darksets the colours for this frame only. Pick the one that matches your Backstage theme.member=<name>shows one member of a declared workspace, such as a Terraform root, and nothing else. On the multi-file site,focus=<box>brings the named box forward and leaves the others in view, so for one component usemember. The one-file viewer readsfocusdifferently, as the last section says.
If the host is not allowed, TechDocs removes the whole iframe and the page shows the rest. Put the image from the section above under the frame and the page still shows the graph:
<iframe ...></iframe>
In the scratch Backstage app the page with the host allow-listed drew the frame and the image. The same page with the allow-list line removed had no iframe, and the image (a PNG of the export, kept in docs/graph/) rendered at its full width.
A frame of the one-file viewer
Section titled “A frame of the one-file viewer”When the export writes behold.html (the single-file viewer, behold#1070), a component’s root can be framed from graph.json with behold.html?src=graph.json&focus=<root>. focus cuts the document around the named box or card with behold’s own cut, the one behold graph --around and the Backstage tab run, one hop out, and draws only that cut. <root> is a box id (stack:prod), a bare box name (prod) or a card id, and a comma list names several. A name the document does not hold is ignored and the whole document is drawn. The cards of a resource with count are drawn in the parent box, so a cut around a root leaves them out and keeps the folded card for the group. The viewer reads src only from its own origin, so it has to be served from the same site as the graph.json it opens.
In the scratch Backstage app, a TechDocs page framing behold.html?src=graph.json&focus=behold-sandbox/app&theme=light from the sandbox export drew 3 cards, the root’s own, with none dimmed. A page that posts behold:view with a focus to the viewer gets the same cut. The node parameter still lights one card and dims the rest. This form is not in a release yet, so use member until it is.
Hosting the export
Section titled “Hosting the export”GitHub Pages and an S3 static website host serve the export as ordinary static files, and the export adds no frame restrictions of its own. A CDN, a bucket policy or the host’s own settings can add X-Frame-Options or frame-ancestors, so open the frame once from your Backstage origin after you publish. A host that sets frame-ancestors has to list the Backstage origin.
What was opened as a frame from the scratch Backstage app above:
- GitHub Pages: the sandbox export at
https://intentius.io/behold-sandbox/drew its graph. - A static bucket: the same export uploaded to a bucket on a local S3-compatible server (MinIO, anonymous read on the bucket, fake local credentials) drew its graph from
http://localhost:19000/sandbox-site/index.html?embed=1&bare=1&theme=light. MinIO answers the S3 object API and has no website endpoint. A request for the bucket root finds no index document, so the frame address namesindex.html. A real S3 static website endpoint serves the index document for the root and an error document of its own, over HTTP only. None of that was run here. The host and port of the framed address go inallowedIframeHosts(localhost:19000in the check).
The export is a snapshot: the frame shows the graph as of the last publish. Setting this up in a Backstage plugin or an MkDocs plugin is not part of this recipe.