Fix CI hang: Don't try to render Graphviz diagrams with GFM

[nrichers]

Pull Request Description

What and why?

The "Validate LLM markdown render" CI step was consistently hanging on site/developer/how-to/testing-overview.qmd, the only file in the codebase that contains {dot} graphviz diagrams inside a .panel-tabset.

Root cause: When Quarto renders to GFM format, it attempts to render graphviz diagrams to PNG using Chrome. This was causing the CI to hang indefinitely.

Fix: After some experiments, I ended up replacing the diagrams with PNG files for now. For local testing, I added a make render-llm action for local troubleshooting but I cannot replicate the issue. Also noticed we were getting pandoc errors during the cleanup phase that removes some HTML tags that make it past the GFM render, now fixed.

Other stuff I tried: I tried a conditional exclude and installing chromium but the content render still hung on the diagrams on GitHub, likely because of the sequence in which Quarto renders the content. Because the issue occurs only on GitHub, troubleshooting is slow going.

Moral of the story: diagrams in tabs are problematic.

How to test

• Try the live preview to ensure HTML output still shows the diagrams: How to run tests and test suites
• Verify the LLM markdown step completed in this workflow run (the .tabset warnings are OK): https://github.com/validmind/documentation/actions/runs/23461255784/job/68263189315?pr=1230

What needs special review?

N/A

Dependencies, breaking changes, and deployment notes

None

Release notes

N/A — internal CI fix

Checklist

• What and why
• How to test
• Labels applied
• PR linked to Shortcut

[github-actions]

Lighthouse check results

⚠️ WARN: Average accessibility score is 0.87 (required: >0.9) — Check the workflow run

Show Lighthouse scores

Folder depth level checked: 0

Commit SHA: fd50d0d

Modify the workflow to check a different depth:

• 0: Top-level navigation only — /index.html, /guide/guides.html, ...
• 1: All first-level subdirectories — /guide/.html, /developer/.html, ...
• 2: All second-level subdirectories — /guide/attestation/*.html, ...

Page	Accessibility	Performance	Best Practices	SEO
/developer/validmind-library.html	0.85	0.66	1.00	0.82
/get-started/get-started.html	0.85	0.71	1.00	0.73
/guide/guides.html	0.81	0.75	1.00	0.82
/index.html	0.93	0.69	1.00	0.82
/releases/all-releases.html	0.86	0.69	1.00	0.73
/support/support.html	0.91	0.68	1.00	0.82
/training/training.html	0.85	0.62	0.96	0.73

[github-actions]

PR Summary

This PR introduces a new feature to render the site into GitHub Flavored Markdown (GFM) tailored for LLM ingestion. To support this, the PR makes several key changes:

1. GitHub Workflows Updates:

   • In both the publish and validation workflows, additional steps have been added to install Pandoc using APT. This ensures that the environment has the necessary tools to convert documentation to markdown during CI runs.

2. Makefile Enhancements:

   • A new phony target named render-llm is added along with an update to the PHONY list. This target echoes messages and runs the llm/render.sh and llm/clean.sh scripts to transform the site content for LLM ingestion. The output is directed to the llm/_llm-output/ directory.

3. Documentation Update:

   • The testing overview documentation has been updated to replace inline dot diagram definitions with static images. This reduces clutter in the markdown file and ensures that users see pre-rendered diagrams, which likely improves load times and compatibility.

Overall, these modifications streamline the process of rendering documentation for LLM applications and ensure that CI workflows are correctly configured to support the necessary tools.

Test Suggestions

• Verify that the GitHub workflows correctly install Pandoc and that the commands run without errors.
• Test the new render-llm Makefile target locally to ensure it successfully executes the rendering and cleaning scripts and outputs the expected files.
• Check that the updated documentation displays the images correctly and that the links to the generated images work as intended.
• Run the LLM rendering process in a staging environment to ensure that the overall documentation output is as expected.

[validbeck]

Looks good, just made a quick adjustment in commit #60365ee to remove the white background from the images that wasn't there in the original version of the charts:

[github-actions]

Validate docs site

✓ INFO: A live preview of the docs site is available — Open the preview