stackql-registry-docs

This repository contains documentation for StackQL providers, which is published to registry.stackql.io. This website is built using Docusaurus 2, a modern static website generator.

Build and Deploy Status

Type	Status	Link
GitHub Actions Build		stackql-registry-docs/actions
Netlify Deploy Base		registry.stackql.io

Adding Docs for a New Provider

Adding docs for a new provider requires creating a new web property (subdomain) and will force an update to the root/base site and all other providers. The steps are:

• update scripts/docgen/provider_data.py with metadata for new provider (not applicable if docs are built elsewhere)
• generate docs for provider using cd scripts; sh docgen.sh {provider} (not applicable if docs are built elsewhere)
• publish docs for provider using cd scripts; sh publish.sh {provider} (not applicable if docs are built elsewhere)
• add the new provider docs to docs/{provider}-docs (following directory structure of existing providers) (done automatically by scripts/publish.sh)
• update frontmatter in the index.md at the root of the new providers docs, set slug to /providers/{provider} and id to {provider}-doc (done automatically by scripts/docgen.sh)
• update stackql-provider-registry.mdx in the root of the new provider to add the currentProvider prop, e.g. <RegistryPage currentProvider="okta" /> (done automatically by scripts/docgen.sh)
• create a new netlify site (stackql-{provider}-docs) - use yarn build:{provider} as the build command
• stop automatic builds for site in Netlify
• add NETLIFY record in Netlify DNS (mapping {provider}-docs.stackql.io (Primary Domain) and {provider}.stackql.io (Domain Alias) to stackql-{provider}-docs.netlify.app), select Force HTTPS
• add GitHub Actions secret for netlify site id - NETLIFY_SITE_ID_{PROVIDER}
• add the Netlify deploy status badge to the table in this README (see above)
• update the providers array in sidebars.js with the new provider
• update the providers array src/configs/providers.ts with the new provider
• update package.json with new start and build scripts
• update allProviders in ci-scripts/get-providers-to-deploy.js with the new provider
• add the root site redirects for provider vanity urls to .github/workflows/build-docs.yaml to the add redirects to root site step of the deploy-to-netlify job

Updating Existing Provider Docs

To update the docs for an existing provider, edit the corresponding markdown file or files in the {provider}-docs directory. Raise a pull request into the main branch. Once merged, the updated docs will be automatically published.

Running Locally

Install packages:

yarn

To build a microsite locally, use yarn build:{provider}. For example, to build the AWS microsite locally, run:

export NODE_OPTIONS=--max_old_space_size=4096
yarn run build:aws

To run a microsite locally, use yarn start:{provider}. For example, to run the AWS microsite locally, run:

yarn start:aws