USWDS Gatsby API Docs Starter

The USWDS Gatsby API Docs Starter is an open-source Gatsby boilerplate for building API documentation hubs with US Web Design System styling and an embedded Swagger UI sandbox.

What is the USWDS Gatsby API Docs Starter?

This starter template, created by Softrams, pairs the Gatsby static site generator with the US Web Design System (USWDS) and Swagger UI to publish documentation for one or more API products on a single hub site. It takes Markdown content and a Swagger/OpenAPI JSON file as input and produces a static Progressive Web App with API reference pages, guides, and an interactive sandbox for trying API calls. The project is an open-source pilot; it is not endorsed, sponsored, or funded by the US Government or any federal agency.

What makes this starter stand out?

• USWDS integration — The site uses the US Web Design System, giving federal agencies a consistent and accessible design language without building their own.
• Swagger UI sandbox — Swagger UI is included so visitors can call endpoints directly; you just replace static/assets/swagger.json with your own OpenAPI file.
• Markdown-driven content — API references live in the docs folder and guides in the guides folder; new guides are automatically added to the site menu.
• Multi-API hub concept — Supports a single API or a suite of APIs, with placeholder pages tailored to organizations at different levels of API maturity.
• Code highlighting with Prism — Source code blocks are highlighted for better readability.
• GitHub Pages deployment — One command, npm run deploy, publishes the static site to GitHub Pages.

Who should use this starter?

• Federal agencies and contractors — Teams that need a USWDS-compliant API documentation site can start from this template instead of creating a design system from scratch.
• FHIR API developers — Organizations publishing one or more FHIR APIs can present endpoints and a live sandbox in a single hub.
• Documentation teams — Writers who prefer Markdown can add or edit reference pages and guides without touching React code.

What can you do with it?

• Publish an API hub — Present multiple API products with consistent navigation and USWDS styling on one site.
• Embed a live API sandbox — Let developers test endpoints directly via Swagger UI using your own swagger.json file.
• Deploy quickly to GitHub Pages — Use npm run deploy to publish the site without managing a server.

How does it work?

Create a new site with the Gatsby CLI command shown in the quick start section, then run gatsby develop to start editing at localhost:8000. Markdown files in the docs and guides folders become pages automatically, and the swagger.json file in static/assets drives the embedded sandbox. Modify pages/swagger.js when you need to change Swagger UI behavior.

Pros and cons

• Pros — Built on USWDS for accessibility; Markdown keeps content maintainable; one-command GitHub Pages deployment; includes Swagger UI.
• Cons — Headless CMS integration is still on the roadmap and not yet implemented; the template is not an official US government product.

Pricing

The starter is free and open source. The project page lists no paid tiers or licensing fees.

Alternatives

• Docusaurus — A React-based static documentation site generator that also supports Markdown and is a popular choice for open-source project docs.

FAQ

Is the USWDS Gatsby API Docs starter free?

Yes, the starter is open source and free to use. It was initially built by Softrams and shared publicly with the community.

How do I add a new API reference page?

Create a new Markdown file in the docs folder. The page will automatically be included in the API reference section with the same layout as the placeholder pages.

How do I use my own Swagger/OpenAPI file?

Replace the swagger.json file in the static/assets folder with your own API definition. You can also edit pages/swagger.js to adjust how Swagger UI is configured.

Can I use this template for non-FHIR APIs?

Yes. The template is designed for REST APIs in general, though it includes placeholder content tailored to FHIR APIs. You can rename pages and rewrite the Markdown to document any REST endpoints.

How do I deploy the site?

Run the command npm run deploy to publish the built site to GitHub Pages. The quick start instructions also show how to run the site locally with gatsby develop.