Skip to content

Render workflow diagrams from JSON instead of screenshots - #505

Merged
methodofaction merged 2 commits into
mainfrom
react-workflows
Jul 28, 2026
Merged

Render workflow diagrams from JSON instead of screenshots#505
methodofaction merged 2 commits into
mainfrom
react-workflows

Conversation

@methodofaction

@methodofaction methodofaction commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

What changed

Workflow modules across all guides now render a console-style diagram directly from each workflow's JSON, replacing screenshots (France) and the four-tab Template/Workflow/Code/Build-from-scratch layout everywhere else.

  • New snippets/components/workflow.jsx: WorkflowDiagram renders numbered steps, branch rails with code chips, // notes, state chips (via Mintlify's Badge with a square icon), and per-provider icons resolved by longest-prefix match against a providerIcons map (per-action entries override app-wide ones; unknown providers render an empty square).
  • Data snippets: every guide-embedded workflow snippet gains an export-only sibling <name>-data.mdx holding the same JSON as a uniquely named export const. Guides import it and pass it to the component.
  • Module layout unified to the France pattern: horizontal "Add to my workspace →" card, then two tabs — Workflow (diagram) and Code (copy-paste JSON). Template tabs were hoisted into the cards, Build from scratch tabs were removed (redundant with the diagram — content recoverable from git history), and JSON tab labels renamed to Code.
  • The six France PA workflow screenshots under assets/guides/ are deleted; no more screenshot maintenance.

Why

Capturing and updating console screenshots for every workflow change doesn't scale. Rendering from the JSON keeps the visual in lockstep with the actual template and gives every country guide the same UX for free.

Reviewer notes

  • Sync requirement: a workflow's JSON now lives twice — the fenced block in <name>.mdx (Code tab, also embedded by apps pages) and the const in <name>-data.mdx (diagram). Updates must be pasted into both. Documented in CLAUDE.md.
  • Why separate data files: a snippet mixing markdown content and const exports compiles to an undefined stub on a fresh Mintlify build (warm dev servers mask it), and export names must be globally unique and imported without aliasing. Also in CLAUDE.md.
  • Icon URLs were all verified against the CDN. Judgment calls worth a glance: gov-pl→ksef, gov-sa→zatca, gov-ar→arca, ticket-it→agenzia-entrate, chorus-pro→apps/chroruspro (CDN slug typo), plemsi→Colombia flag, and gov-es.noverifactu falls back to the generic gov-es icon.
  • Verified locally on fresh mint dev builds across representative guides (light + dark): diagrams, icons, cards, tabs, and mint broken-links all clean.

🤖 Generated with Claude Code

@methodofaction @claude
Render workflow diagrams from JSON with a WorkflowDiagram component
11ee383 
Replace workflow screenshots and four-tab modules with a console-style
diagram rendered directly from each workflow's JSON:

- Add snippets/components/workflow.jsx: WorkflowDiagram renders numbered
  steps, branches, notes, state chips (Mintlify Badge), and per-provider
  icons resolved by longest-prefix match against a providerIcons map.
- Pair every guide-embedded workflow snippet with an export-only
  <name>-data.mdx holding the same JSON as a uniquely named const;
  guides import it and pass it to the component. Snippets mixing
  markdown content with const exports break Mintlify's fresh compile,
  hence the separate data files.
- Restructure all workflow modules across guides to the France pattern:
  horizontal "Add to my workspace" card, then two tabs (Workflow, Code).
  Drop Template and Build-from-scratch tabs; rename JSON tabs to Code.
- Delete the now-unused France workflow screenshots.

Both files of a snippet pair must stay in sync when a workflow changes;
CLAUDE.md documents this and the Mintlify compile constraints.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings July 28, 2026 10:19
@mintlify

mintlify Bot commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
invopop 🟢 Ready View Preview Jul 28, 2026, 10:22 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

Copilot AI reviewed Jul 28, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates the Mintlify docs site to render workflow diagrams directly from workflow JSON (via a shared WorkflowDiagram component) instead of relying on screenshots and multi-tab layouts, and refactors many guides to use a unified “Add to my workspace →” card + “Workflow/Code” tabs pattern.

Changes:

  • Added a reusable WorkflowDiagram component that renders console-style steps (including branching, notes, state chips, and provider icons).
  • Introduced *-data.mdx export-only workflow snippets (mirroring the JSON in the existing fenced-code snippets) for guide-embedded diagrams.
  • Updated multiple guides to use the new diagram + simplified tabs layout; documented the new workflow snippet pairing convention in CLAUDE.md.

Reviewed changes

Copilot reviewed 135 out of 141 changed files in this pull request and generated 5 comments.

Show a summary per file
File Description
snippets/components/workflow.jsx Adds WorkflowDiagram renderer with provider icon mapping and state-chip rendering.
snippets/workflows/stripe/stripe-verifactu-data.mdx Adds export-only workflow JSON for Stripe VERI*FACTU example diagram.
snippets/workflows/stripe/stripe-invoice-data.mdx Adds export-only workflow JSON for Stripe basic PDF example diagram.
snippets/workflows/sa/sa-unregister-data.mdx Adds export-only workflow JSON for ZATCA unregister workflow diagram.
snippets/workflows/sa/sa-send-invoice-data.mdx Adds export-only workflow JSON for ZATCA send invoice workflow diagram.
snippets/workflows/sa/sa-register-data.mdx Adds export-only workflow JSON for ZATCA register workflow diagram.
snippets/workflows/pt/at-register-supplier-data.mdx Adds export-only workflow JSON for Portugal AT supplier registration workflow diagram.
snippets/workflows/pt/at-postregistration-data.mdx Adds export-only workflow JSON for Portugal AT post-registration workflow diagram.
snippets/workflows/pt/at-issue-payment-data.mdx Adds export-only workflow JSON for Portugal AT payment issuance workflow diagram.
snippets/workflows/pt/at-issue-invoice-data.mdx Adds export-only workflow JSON for Portugal AT invoice issuance workflow diagram.
snippets/workflows/pt/at-issue-delivery-data.mdx Adds export-only workflow JSON for Portugal AT delivery issuance workflow diagram.
snippets/workflows/pt/at-cancel-payment-data.mdx Adds export-only workflow JSON for Portugal AT payment cancellation workflow diagram.
snippets/workflows/pt/at-cancel-invoice-data.mdx Adds export-only workflow JSON for Portugal AT invoice cancellation workflow diagram.
snippets/workflows/pt/at-cancel-delivery-data.mdx Adds export-only workflow JSON for Portugal AT delivery cancellation workflow diagram.
snippets/workflows/pl/pl-sync-data.mdx Adds export-only workflow JSON for Poland KSeF sync workflow diagram.
snippets/workflows/pl/pl-send-data.mdx Adds export-only workflow JSON for Poland KSeF invoice issuance workflow diagram.
snippets/workflows/pl/pl-register-receive-data.mdx Adds export-only workflow JSON for Poland KSeF registration (receive) workflow diagram.
snippets/workflows/pl/pl-register-data.mdx Adds export-only workflow JSON for Poland KSeF registration (send) workflow diagram.
snippets/workflows/pl/pl-import-data.mdx Adds export-only workflow JSON for Poland KSeF import workflow diagram.
snippets/workflows/peppol/unregister-data.mdx Adds export-only workflow JSON for Peppol unregister workflow diagram.
snippets/workflows/peppol/send-data.mdx Adds export-only workflow JSON for Peppol send invoice workflow diagram.
snippets/workflows/peppol/register-data.mdx Adds export-only workflow JSON for Peppol register workflow diagram.
snippets/workflows/peppol/receive-data.mdx Adds export-only workflow JSON for Peppol receive invoice workflow diagram.
snippets/workflows/pdf/invoice-data.mdx Adds export-only workflow JSON for basic PDF invoice workflow diagram.
snippets/workflows/mx/sw-sapien-register-party-data.mdx Adds export-only workflow JSON for SW Sapien party registration workflow diagram.
snippets/workflows/mx/sw-sapien-import-cfdi-data.mdx Adds export-only workflow JSON for SW Sapien bulk CFDI import workflow diagram.
snippets/workflows/mx/sat-unregister-supplier-data.mdx Adds export-only workflow JSON for SAT unregister supplier workflow diagram.
snippets/workflows/mx/sat-register-supplier-data.mdx Adds export-only workflow JSON for SAT register supplier workflow diagram.
snippets/workflows/mx/sat-postregistration-data.mdx Adds export-only workflow JSON for SAT post-registration workflow diagram.
snippets/workflows/mx/sat-platforms-unregister-data.mdx Adds export-only workflow JSON for SAT platforms unregister workflow diagram.
snippets/workflows/mx/sat-platforms-register-data.mdx Adds export-only workflow JSON for SAT platforms register workflow diagram.
snippets/workflows/mx/sat-platforms-record-data.mdx Adds export-only workflow JSON for SAT platforms record operation workflow diagram.
snippets/workflows/mx/sat-issue-payment-data.mdx Adds export-only workflow JSON for SAT issue payment workflow diagram.
snippets/workflows/mx/sat-issue-invoice-data.mdx Adds export-only workflow JSON for SAT issue invoice workflow diagram.
snippets/workflows/mx/sat-convert-cfdi-data.mdx Adds export-only workflow JSON for SAT import CFDI workflow diagram.
snippets/workflows/mx/mx-subscribe-import-data.mdx Adds export-only workflow JSON for periodic CFDI import subscription workflow diagram.
snippets/workflows/it/ticket-void-receipt-data.mdx Adds export-only workflow JSON for Smart Receipts void workflow diagram.
snippets/workflows/it/ticket-send-data.mdx Adds export-only workflow JSON for Smart Receipts issue workflow diagram.
snippets/workflows/it/ticket-register-supplier-data.mdx Adds export-only workflow JSON for Smart Receipts supplier registration workflow diagram.
snippets/workflows/it/sdi-send-data.mdx Adds export-only workflow JSON for SDI send invoice workflow diagram.
snippets/workflows/it/sdi-register-customer-data.mdx Adds export-only workflow JSON for SDI customer registration workflow diagram.
snippets/workflows/it/sdi-post-registration-flow-data.mdx Adds export-only workflow JSON for SDI post-registration workflow diagram.
snippets/workflows/it/sdi-import-invoices-data.mdx Adds export-only workflow JSON for SDI import invoices workflow diagram.
snippets/workflows/gr/iapr-invoice-data.mdx Adds export-only workflow JSON for Greece IAPR/myDATA invoice workflow diagram.
snippets/workflows/fr/fr-reporting-send-data.mdx Adds export-only workflow JSON for France PPF reporting send workflow diagram.
snippets/workflows/fr/fr-reporting-record-data.mdx Adds export-only workflow JSON for France PPF reporting record workflow diagram.
snippets/workflows/fr/fr-pa-unregister-data.mdx Adds export-only workflow JSON for France PA unregister workflow diagram.
snippets/workflows/fr/fr-pa-register-data.mdx Adds export-only workflow JSON for France PA register workflow diagram.
snippets/workflows/fr/chorus-pro-registration-data.mdx Adds export-only workflow JSON for Chorus Pro supplier registration workflow diagram.
snippets/workflows/fr/chorus-pro-invoice-data.mdx Adds export-only workflow JSON for Chorus Pro invoice workflow diagram.
snippets/workflows/es/verifactu-unregister-data.mdx Adds export-only workflow JSON for VERI*FACTU unregister workflow diagram.
snippets/workflows/es/verifactu-supplier-registration-data.mdx Adds export-only workflow JSON for VERI*FACTU supplier registration workflow diagram.
snippets/workflows/es/verifactu-invoice-data.mdx Adds export-only workflow JSON for VERI*FACTU invoice workflow diagram.
snippets/workflows/es/verifactu-cancel-data.mdx Adds export-only workflow JSON for VERI*FACTU cancel workflow diagram.
snippets/workflows/es/ticketbai-unregister-data.mdx Adds export-only workflow JSON for TicketBAI unregister workflow diagram.
snippets/workflows/es/ticketbai-supplier-registration-data.mdx Adds export-only workflow JSON for TicketBAI supplier registration workflow diagram.
snippets/workflows/es/ticketbai-invoice-data.mdx Adds export-only workflow JSON for TicketBAI invoice workflow diagram.
snippets/workflows/es/ticketbai-cancel-data.mdx Adds export-only workflow JSON for TicketBAI cancel workflow diagram.
snippets/workflows/es/sii-unregister-data.mdx Adds export-only workflow JSON for SII unregister workflow diagram.
snippets/workflows/es/sii-register-data.mdx Adds export-only workflow JSON for SII register workflow diagram.
snippets/workflows/es/sii-record-received-data.mdx Adds export-only workflow JSON for SII record received workflow diagram.
snippets/workflows/es/sii-record-issued-data.mdx Adds export-only workflow JSON for SII record issued workflow diagram.
snippets/workflows/es/noverifactu-unregister-data.mdx Adds export-only workflow JSON for NO VERI*FACTU unregister workflow diagram.
snippets/workflows/es/noverifactu-supplier-registration-data.mdx Adds export-only workflow JSON for NO VERI*FACTU supplier registration workflow diagram.
snippets/workflows/es/noverifactu-summary-event-data.mdx Adds export-only workflow JSON for NO VERI*FACTU summary event workflow diagram.
snippets/workflows/es/noverifactu-invoice-data.mdx Adds export-only workflow JSON for NO VERI*FACTU invoice workflow diagram.
snippets/workflows/es/noverifactu-event-data.mdx Adds export-only workflow JSON for NO VERI*FACTU process event workflow diagram.
snippets/workflows/es/noverifactu-cancel-data.mdx Adds export-only workflow JSON for NO VERI*FACTU cancel workflow diagram.
snippets/workflows/es/facturae-data.mdx Adds export-only workflow JSON for Facturae generate workflow diagram.
snippets/workflows/de/zugferd-data.mdx Adds export-only workflow JSON for ZUGFeRD workflow diagram.
snippets/workflows/de/xrechnung-data.mdx Adds export-only workflow JSON for XRechnung workflow diagram.
snippets/workflows/co/dian-invoice-data.mdx Adds export-only workflow JSON for Colombia DIAN invoice workflow diagram.
snippets/workflows/chargebee/cb-zugferd-data.mdx Adds export-only workflow JSON for Chargebee→ZUGFeRD workflow diagram.
snippets/workflows/chargebee/cb-peppol-data.mdx Adds export-only workflow JSON for Chargebee→Peppol workflow diagram.
snippets/workflows/chargebee/cb-invoice-data.mdx Adds export-only workflow JSON for Chargebee basic PDF workflow diagram.
snippets/workflows/chargebee/cb-dk-peppol-data.mdx Adds export-only workflow JSON for Chargebee→Peppol (DK) workflow diagram.
snippets/workflows/ar/ar-supplier-registration-data.mdx Adds export-only workflow JSON for Argentina ARCA supplier registration workflow diagram.
snippets/workflows/ar/ar-invoice-data.mdx Adds export-only workflow JSON for Argentina ARCA invoicing workflow diagram.
guides/stripe.mdx Replaces prior layout with cards + Workflow/Code tabs using WorkflowDiagram.
guides/sa-zatca-registration.mdx Updates ZATCA registration guide to render workflow diagrams from JSON.
guides/sa-zatca-clearance-reporting.mdx Updates ZATCA clearance/reporting guide to render workflow diagram from JSON.
guides/pt-at-supplier.mdx Updates Portugal AT supplier guide to render workflow diagrams from JSON.
guides/pdf-invoice.mdx Updates PDF invoice guide to render the workflow diagram from JSON.
guides/mx-sat-platform-reporting.mdx Updates Mexico SAT platform reporting guide to render diagrams from JSON.
guides/it-ticket.mdx Updates Smart Receipts invoicing guide to render diagrams from JSON.
guides/it-ticket-supplier.mdx Updates Smart Receipts supplier guide to render diagrams from JSON.
guides/it-sdi-sending.mdx Updates SDI sending guide to render workflow diagram from JSON.
guides/gr-iapr.mdx Updates Greece IAPR guide to render workflow diagram from JSON.
guides/fr-pa-reporting.mdx Replaces screenshot tabs with Workflow/Code tabs rendered from JSON.
guides/fr-pa-registration.mdx Replaces screenshot tabs with Workflow/Code tabs rendered from JSON.
guides/fr-pa-invoicing.mdx Replaces screenshot tabs with Workflow/Code tabs rendered from JSON.
guides/fr-chorus-pro.mdx Updates Chorus Pro invoicing guide to render diagram from JSON.
guides/fr-chorus-pro-supplier.mdx Updates Chorus Pro supplier guide to render diagram from JSON.
guides/es-verifactu.mdx Updates VERI*FACTU guide to render diagrams from JSON.
guides/es-sii.mdx Updates SII guide to render diagrams from JSON.
guides/es-noverifactu.mdx Updates NO VERI*FACTU guide to render diagrams from JSON.
guides/es-facturae.mdx Updates Facturae guide to render diagram from JSON.
guides/de-ubl.mdx Updates Germany guide to render XRechnung/ZUGFeRD diagrams from JSON.
guides/co-dian.mdx Updates Colombia DIAN guide to render diagram from JSON.
guides/chargebee.mdx Updates Chargebee guide to render diagram from JSON.
guides/cb-germany.mdx Updates Chargebee Germany guide to render diagrams from JSON.
guides/cb-france.mdx Updates Chargebee France guide to render diagram from JSON.
guides/cb-denmark.mdx Updates Chargebee Denmark guide to render diagram from JSON.
guides/cb-belgium.mdx Updates Chargebee Belgium guide to render diagram from JSON.
guides/ar-arca-suppliers.mdx Updates ARCA supplier guide to render diagram from JSON.
guides/ar-arca-invoices.mdx Updates ARCA invoices guide to render diagram from JSON.
CLAUDE.md Documents the workflow snippet pairing and export naming constraints.
Comments suppressed due to low confidence (1)

snippets/workflows/mx/sat-platforms-record-data.mdx:39

  • Step name casing is inconsistent (Set State vs the common Set state). For consistency (and to keep the code + data snippets aligned), this should be Set state.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread snippets/workflows/fr/fr-pa-register-data.mdx Outdated
Comment thread snippets/workflows/fr/fr-pa-unregister-data.mdx Outdated
Comment thread snippets/workflows/fr/fr-reporting-send-data.mdx Outdated
Comment thread snippets/workflows/fr/fr-reporting-record-data.mdx Outdated
Comment thread snippets/workflows/mx/sat-platforms-record-data.mdx Outdated
@methodofaction @claude
Apply review feedback: fr export naming convention, Set state casing
9b5dfea 
- Rename the six France data-snippet exports to the documented
  <dir>-<file> camelCase convention (frPaRegisterWorkflow etc.) to
  avoid generic names that risk Mintlify inlining collisions.
- Normalize "Set State" to "Set state" in the MX platforms record
  workflow (both the fence and data copies).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings July 28, 2026 10:26
@methodofaction
methodofaction merged commit a7d842d into main Jul 28, 2026
3 checks passed
@methodofaction
methodofaction deleted the react-workflows branch July 28, 2026 10:29
Copilot AI reviewed Jul 28, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 136 out of 142 changed files in this pull request and generated no new comments.

@mintlify

mintlify Bot commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
invopop 🟡 Building – Jul 28, 2026, 10:19 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

@methodofaction methodofaction mentioned this pull request Jul 28, 2026
Merged
methodofaction added a commit that referenced this pull request Jul 28, 2026
@methodofaction @claude
Add create-country-guide and create-app-page authoring skills
21093eb 
Reverse-engineer the current authoring patterns for country guides
(supplier + issuing pair, workflow snippet pairs, FAQ wiring, docs.json
registration) and apps pages (Tabs shell, actions/workflows/documents
tabs, index card and nav registration) into two packaged skills, so new
countries and apps follow the newest conventions (#498, #504, #505)
instead of legacy pages. Register both in CLAUDE.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@methodofaction