Guide / 02 · Codegen & CI

Keep database diagrams current with your documentation.

Generate the image during the build, then deploy it with the docs. The SVG does not need to be committed to Git.

Add one step to codegen

Install the versioned CLI package and D2 0.7.1 in your build environment. From the root of your project, add this command before the documentation build:

migration-erd ./db/migrations ./docs-site/static/img/schema.svg

Use the complete migration history. No database container, database credentials or SQL execution is needed for supported migrations. Keep the CLI version and D2 version pinned so upgrades are intentional.

If you prefer to keep the runtime under tools/erd-generator/, copy erd_generator/, requirements.txt and .gitignore. Install the Python dependencies in that tool's environment, then call it from the existing script:

PYTHONPATH=./tools/erd-generator \
  ./tools/erd-generator/.venv/bin/python -m erd_generator \
  ./db/migrations ./docs-site/static/img/schema.svg

Reference the SVG in Docusaurus

Docusaurus copies files from static/ into the built site's root. In a Markdown document, add:

![Database schema](/img/schema.svg)

[Open full-size diagram](/img/schema.svg)

Check the deployed URL against your site's baseUrl. For JSX references, follow Docusaurus's static asset and base URL guidance. View SVGs in a browser; some image converters do not support the HTML index captions inside the SVG.

Generate, then build, then deploy

After checkout and dependency installation, the relevant part of a GitHub Actions job can be:

- name: Generate the database diagram
  run: migration-erd ./db/migrations ./docs-site/static/img/schema.svg

- name: Build the documentation
  working-directory: docs-site
  run: npm run build

This snippet assumes the CLI, D2 and your site's Node dependencies are already installed. Deploy the resulting documentation build using your existing deployment job. If build and deploy run in different jobs, transfer artifacts from the same successful run.

Do not use continue-on-error on the generation step. Errors return exit code 1 and preserve the previous requested SVG; an INCOMPLETE partial preview may also be produced. A failed generation should stop publication, preventing an old or incomplete diagram from being presented as current.

Keep generated files out of source control

Put these entries in the parent project's .gitignore; the tool's own ignore file does not cover output paths elsewhere in your repository:

/docs-site/static/img/schema.svg
/docs-site/static/img/schema.partial.svg

Diagnostics go to the terminal by default. Use --log-dir only when you intentionally want diagnostic files as CI artifacts. A full configuration reference is in the developer guide.

Compare the database documentation workflows →