Embed an n8n workflow diagram in a README

Why not just commit a PNG

You can, and for a workflow that will never change again it is the simplest thing that works. The problem is the second edit. Somebody adds an error branch, nobody re-exports the picture, and now the README shows a workflow that no longer exists — which is worse than no picture, because a reader trusts it.

Hosting the image moves the diagram from “a file somebody remembered to update” to “a URL that gets re-rendered by the same pipeline that changes the workflow”.

Setting it up

1. 01
   Get a key

   Free and self-serve at pixtex.dev/developers, or npx pixtex signup you@example.com from a terminal. You confirm by email; the key is shown once and stored only as a hash on our side.

2. 02
   Host the diagram

   One call renders the workflow and parks the PNG at a permanent URL. The response hands back the markdown line, so there is nothing to assemble by hand.

   shell

   npx pixtex push workflows/order-sync.json
   
   # → https://api.pixtex.dev/i/aB3xK9_qLw4.png
   #   ![Order sync](https://api.pixtex.dev/i/aB3xK9_qLw4.png)

3. 03
   Paste it into the README

   It is an ordinary PNG endpoint, which is exactly why it works everywhere: GitHub and GitLab READMEs, Notion, Confluence, dev.to, Medium, Slack unfurls, and the n8n community forum all embed it with no special handling.

4. 04
   Wire up the re-render

   Point a GitHub Action at the workflow file. On the first run leave image-id out so a new image is created, then save the step's image-id output as a repo variable — every run after that updates the same URL in place.

   .github/workflows/pixtex.yml

   name: Update workflow diagram
   on:
     push:
       branches: [main]
       paths: ['workflows/**.json']
   
   jobs:
     render:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: VicegerentPrince/pixtex@v1
           with:
             workflow: workflows/order-sync.json
             api-key: ${{ secrets.PIXTEX_API_KEY }}
             image-id: ${{ vars.PIXTEX_IMAGE_ID }}   # omit on the first run

If the workflow does not live in a repo

Plenty of workflows only exist on an n8n instance, never in git. In that case the re-render can run inside n8n itself, using the verified n8n-nodes-pixtex community node:

Schedule Trigger  →  n8n (Get Workflow)  →  Pixtex (Hosted Image · Update)

Three nodes on a nightly schedule and the diagram in your documentation re-renders itself, with no CI and no terminal involved. The Pixtex node takes the n8n node's Get Workflow output as-is, so a workflow can document itself — including the one it is running in.

Details that make the embed look right

• Pick a frame. The og preset renders at Open Graph proportions, which is what social cards and most docs themes expect. auto sizes to the workflow.
• Match your docs theme. Backgrounds run from dark and midnight through white and paper, plus transparent — GitHub serves two themes, so transparent or a background that reads on both is the safe choice.
• Turn down the detail on big flows. nodeDetail: "minimal" keeps a 60-node workflow legible at README width where detailed turns to noise.
• Set alt text. The markdown Pixtex returns uses the image name — give it a real one, because that alt text is what a screen reader and a crawler actually read.