Cadence docs is built using Docusaurus.

📚 New to contributing to Cadence? Check out our Contributing Guide for an overview of the contribution process across all Cadence repositories. This document contains Cadence backend specific setup and development instructions.

npm install

npm run start

This command starts a local development server and opens up a browser window at http://localhost:3000/. Most changes are reflected live without having to restart the server.

npm run build

This command generates static content into the build directory and can be served using any static contents hosting service.

Our website is deployed by using GitHub pages, which are static HTML pages generated from the codebase whereas npm run start runs Docusaurus in development mode, injecting styles and updates them with HMR. Before you land your changes you need to check how they are going to look like in the website. Here are the steps to perform that test:

Run this once:

chmod +x scripts/preview-github-pages-build.sh

Run this before every test:

./scripts/preview-github-pages-build.sh --serve      # then open http://localhost:4173/

Alternatively, you can run the following:

npm run preview:github-pages -- --serve

In order to deploy to multiple environments, some configuration options in docusaurus.config.ts are made available for override through environment variables.

# Can be replaced by your GH pages URL, i.e., https://<userId>.github.io/
CADENCE_DOCS_URL=https://cadenceworkflow.io

# For GitHub Pages project sites (e.g. username.github.io/Cadence-Docs/), use /<repo>/
# Official cadenceworkflow.io build uses BASE_URL=/
BASE_URL=/Cadence-Docs/

# For GitHub pages only, this is your GitHub org/user name.
ORGANIZATION_NAME=cadence-workflow

A file static/CNAME should be present to use a custom domain for GitHub Pages (e.g. cadenceworkflow.io). The deploy workflow creates it from secrets.CUSTOM_DOMAIN (finnp/create-file-action).

Using SSH:

USE_SSH=true npm run deploy

Not using SSH:

GIT_USER=<Your GitHub username> npm run deploy

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages branch.

The release pages rely on data from GitHub that is persisted as JSON files under static/data/releases/. In order to update the release information for display, this can be done manually or be set up as part of the CI/CD process by running the scripts/fetch-releases.sh script. Script uses the GitHub CLI to fetch the release data.

Automatic updates to release data are performed by a GitHub Action fetch-release-data, which will check if new data is available, and if so, update the release data with the latest information and open a branch named fetch-release-data and open a PR if one is not open already.

Manual approval is required before merging and continuing to deployment.

Ensure you have a .npmrc file configured with registry=https://registry.npmjs.org/. This will ensure the dependencies are pulled from the correct source and to prevent internal npm registries from being pushed onto the package-lock.json

The source code in this repository is licensed under the Apache 2.0 License. The documentation in this repository is licensed under the Creative Commons Attribution 4.0 International License. See LICENSE for details.