Guides Graphs Laravel Package

Getting Started

1. Install the package via Composer:

   composer require --dev phpdocumentor/guides-graphs
   

2. Ensure phpdocumentor/guides (v3+) is installed and configured — guides-graphs is a plugin for Guides, not a standalone tool.
3. Define a graph in your markdown using the fenced code block syntax, e.g.:

   ```graphviz
   digraph G {
       A -> B;
       B -> C;
       A -> C [label="direct"];
   }
   ```
   

4. Build your documentation using phpdocumentor guide:build. The graph will be automatically rendered (default: SVG) and embedded in the output.

💡 First use case: Embed system architecture diagrams directly in your API docs to keep them in sync with code — update the DOT source, rebuild, and the diagram updates.

Implementation Patterns

• Inline graphs in markdown files for tight coupling between docs and code (e.g., in reference/system-design.md).
• Use theme_options.graphs.renderers in guide.yaml to configure renderer preferences or fallbacks:

  theme_options:
    graphs:
      renderers:
        graphviz:
          format: svg
          engine: dot
  

• Leverage extensibility: Add custom renderers by registering services tagged with guides_graphs.renderer. Ideal for internal DSLs (e.g., plantuml, mermaid, or domain-specific diagram formats).
• CI-friendly rendering: All renders are deterministic — use in CI to generate a consistent assets/graphs/ folder for deployment.
• Theme-aware integration: Guides themes automatically pick up rendered outputs; no extra HTML or <img> tags needed — just the code block.

🔄 Workflow tip: Start with Graphviz (DOT) for quick prototyping, then refactor complex diagrams to custom renderers as your docs mature.

Gotchas and Tips

• ⚠️ Missing Graphviz binary? The default Graphviz renderer requires dot on $PATH. In containerized/CI builds, ensure it’s installed (apt-get install graphviz on Debian/Ubuntu).
• ⚠️ SVG-only by default: If your theme or mobile audience prefers PNG, configure format: png and verify font rendering consistency (embed fonts if needed).
• 📁 Output location: Rendered assets land in output/{theme}/assets/graphs/ by default — double-check this path aligns with your static host’s asset strategy.
• 🔄 Incremental builds: Guides caches renders. Use --force to rebuild all graphs (e.g., when updating the DOT library or renderer config).
• 🧪 Debug rendering issues:
  • Add --debug to the guide:build command to see renderer logs.
  • Temporarily disable caching in guide.yaml (cache: false).
• 🔌 Extension point: The GuidesGraphsExtension class is your entry for registering custom renderers — register services in services.yaml or a custom extension class.
• 🧩 No native Mermaid support: Though the architecture supports it, you’ll need to write a custom renderer (see src/Renderer/GraphvizRenderer for reference).