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
Netlify Deploy AWS		aws-docs.stackql.io aws.stackql.io
Netlify Deploy Azure		azure-docs.stackql.io azure.stackql.io
Netlify Deploy Azure Extras		azure-extras-docs.stackql.io azure-extras.stackql.io
Netlify Deploy Firebase		firebase-docs.stackql.io firebase.stackql.io
Netlify Deploy GitHub		github-docs.stackql.io github.stackql.io
Netlify Deploy Google		google-docs.stackql.io google.stackql.io
Netlify Deploy K8S		k8s-docs.stackql.io k8s.stackql.io
Netlify Deploy Netlify		netlify-docs.stackql.io netlify.stackql.io
Netlify Deploy Okta		okta-docs.stackql.io okta.stackql.io
Netlify Deploy Sumologic		sumologic-docs.stackql.io sumologic.stackql.io
Netlify Deploy Digital Ocean		digitalocean-docs.stackql.io digitalocean.stackql.io
Netlify Deploy Linode		linode-docs.stackql.io linode.stackql.io
Netlify Deploy Vercel		vercel-docs.stackql.io vercel.stackql.io
Netlify Deploy Godaddy		godaddy-docs.stackql.io godaddy.stackql.io
Netlify Deploy PagerDuty		pagerduty-docs.stackql.io pagerduty.stackql.io
Netlify Deploy Homebrew		homebrew-docs.stackql.io homebrew.stackql.io
Netlify Deploy Datadog		datadog-docs.stackql.io datadog.stackql.io
Netlify Deploy Azure ISV		azure-isv-docs.stackql.io azure-isv.stackql.io
Netlify Deploy Azure Stack		azure-stack-docs.stackql.io azure-stack.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
• generate docs for provider using cd scripts; sh docgen.sh {provider}
• publish docs for provider using cd scripts; sh publish.sh {provider}
• 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