Skip to content

README.md

Latest commit

 

History

History
103 lines (76 loc) · 5.72 KB

README.md

File metadata and controls

103 lines (76 loc) · 5.72 KB
Raw

SpectaQL configuration

This directory contains SpectaQL configuration files for generating the Adobe Commerce GraphQL API reference as Markdown fragments embedded in the documentation site via Edge Delivery Services.

Prerequisites

  • Node.js matching the version in .nvmrc
  • npm

Files overview

File Role
config.yml SpectaQL config for the latest (2.4.9) schema (schema.json → split chunk files).
config_2-4-8.yml SpectaQL config for the 2.4.8 schema.
config_2-4-7.yml SpectaQL config for the 2.4.7 schema.
config_2-4-6.yml SpectaQL config for the 2.4.6 schema.
config_saas.yml SpectaQL config for the Adobe Commerce as a Cloud Service schema.
schema.json GraphQL introspection result — latest (2.4.9).
schema_2-4-8.json GraphQL introspection result — 2.4.8.
schema_2-4-7.json GraphQL introspection result — 2.4.7.
schema_2-4-6.json GraphQL introspection result — 2.4.6.
schema_saas.json GraphQL introspection result — Adobe Commerce as a Cloud Service.
markdown-theme/ Custom SpectaQL Handlebars theme that outputs a plain Markdown fragment instead of HTML.
markdown-grunt-config.js Custom grunt task config that disables SpectaQL's HTML prettifier, which would otherwise collapse the Markdown output to a single line.
scripts/generate-spectaql-md.js Build script. Runs SpectaQL once per schema, splits the output into per-section chunk files, removes SpectaQL's JS/CSS asset output, and syncs the reference pages that embed each chunk via a single Fragment include.

How it works

The script reads each local introspection file, runs SpectaQL with a custom Markdown-output theme, and splits the monolithic output into smaller chunk files written to src/pages/includes/autogenerated/. Each chunk is embedded in its own reference page via a single Fragment directive that the script maintains automatically:

<!-- src/pages/reference/graphql/latest/index.md -->
<Fragment src="../../../includes/autogenerated/graphql-api-2-4-9-queries.md" />

<!-- src/pages/reference/graphql/latest/mutations.md -->
<Fragment src="../../../includes/autogenerated/graphql-api-2-4-9-mutations.md" />

<!-- src/pages/reference/graphql/latest/types-a-b.md -->
<Fragment src="../../../includes/autogenerated/graphql-api-2-4-9-types-a-b.md" />
…

The deployment system imposes a size limit on individual Markdown files, and loading every chunk on one page defeats the purpose of splitting. Types are therefore split into fixed alphabetical ranges (types-a-b, types-c-e, types-f-i, types-k-p, types-q-s, types-t-z), each mapped to its own reference page. Queries and mutations are separate pages as well.

Generate the API reference

To regenerate all schema versions:

npm run generate:graphql-api-docs

To regenerate a single version:

npm run generate:graphql-api-docs:2.4.9
npm run generate:graphql-api-docs:2.4.8
npm run generate:graphql-api-docs:2.4.7
npm run generate:graphql-api-docs:2.4.6
npm run generate:graphql-api-docs:saas

What happens for each schema:

  1. Any existing chunk files for that version (graphql-api-X-Y-Z-*.md) are deleted so stale files do not persist if the schema shrinks.
  2. SpectaQL reads the local schema file using the corresponding config_*.yml.
  3. The custom markdown-theme/ Handlebars templates render a single Markdown document.
  4. The custom markdown-grunt-config.js bypasses the HTML prettifier.
  5. SpectaQL's JS/CSS asset directories are removed from the output directory.
  6. The document is split by H2 section into *-queries.md, *-mutations.md, and (if present) *-subscriptions.md.
  7. The types section is split into fixed alphabetical ranges: *-types-a-b.md, *-types-c-e.md, *-types-f-i.md, *-types-k-p.md, *-types-q-s.md, and *-types-t-z.md (split at H3 boundaries).
  8. The script writes or updates separate reference pages under src/pages/reference/graphql/ (index.md, mutations.md, and types-*.md) so each page embeds exactly one chunk file.

Update the API reference

If a schema changes:

  1. Replace the relevant schema_X.Y.Z.json with the updated introspection result.

  2. Create a branch from main and regenerate only that version:

    npm run generate:graphql-api-docs:X.Y.Z

  3. Review the updated chunk files in src/pages/includes/autogenerated/ and the updated reference pages in the corresponding src/pages/reference/graphql/ directory.

  4. Commit all changed files (chunk files + reference pages if the page layout changed).

  5. After the PR is approved and merged, the updated reference is published automatically via EDS.

Add a new schema version

  1. Drop the introspection file into spectaql/schema_X.Y.Z.json.
  2. Copy config_2-4-8.yml to config_X.Y.Z.yml and update introspectionFile, targetFile, version, and title.
  3. Add an entry (with version, config, and indexDir fields) to the schemas array in scripts/generate-spectaql-md.js.
  4. Add a generate:graphql-api-docs:X.Y.Z script to package.json.
  5. Create src/pages/reference/graphql/X-Y-Z/index.md with the appropriate frontmatter and heading (no Fragment lines needed — the script writes the reference pages on first run).
  6. Add the version's sub-pages to src/pages/config.md (queries, mutations, and the six types ranges).
  7. Run npm run generate:graphql-api-docs:X.Y.Z and commit the result.

Notes

  • The mdTypeLink helper override in markdown-theme/helpers/ generates GFM-compatible #typename anchors instead of SpectaQL's default #definition-TypeName format, which requires <a> tags not supported by EDS.
  • Sass @import deprecation warnings during the build are cosmetic and do not affect output.