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.
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 byscripts/publish.sh
) - update frontmatter in the
index.md
at the root of the new providers docs, setslug
to/providers/{provider}
andid
to{provider}-doc
(done automatically byscripts/docgen.sh
) - update
stackql-provider-registry.mdx
in the root of the new provider to add thecurrentProvider
prop, e.g.<RegistryPage currentProvider="okta" />
(done automatically byscripts/docgen.sh
) - create a new netlify site (
stackql-{provider}-docs
) - useyarn build:{provider}
as thebuild 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) tostackql-{provider}-docs.netlify.app
), selectForce 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 insidebars.js
with the new provider - update the
providers
arraysrc/configs/providers.ts
with the new provider - update
package.json
with newstart
andbuild
scripts - update
allProviders
inci-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 theadd redirects to root site
step of thedeploy-to-netlify
job
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.
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