FusionAuth Site

Despite the name, this repo only contains the FusionAuth documentation, articles, developer tools, and blog.

This content is hosted in the following subdirectories of fusionauth.io:

• https://fusionauth.io/docs
• https://fusionauth.io/blog
• https://fusionauth.io/articles

The FusionAuth site is open source. Found a bug, an issue, or a typo in our docs? File an issue or submit a pull request.

Code examples

Code examples accompanying guides each have their own repository.

There is currently work in progress to move each repository into the folder in this documentation repository: astro/src/code-example-repositories. This local folder is where the code examples are maintained and updated. This folder is pushed to the external repositories, which are now readonly to all users except the documentation account.

All code examples have only one branch, main, because otherwise the documentation repository would be polluted with multiple branch names, and we wouldn't know which branches relate which code repositories when trying to export to remote repositories.

For guides that are self-contained (readers type code from scratch rather than cloning a repository), there is no external repository to export to. Store these code examples in astro/src/code-example-repositories like any other example, but set the contents of repositoryUrl.txt to internal. The export workflow will skip these repositories.

Code snippets used to be generated by the custom RemoteCode component, which pulled snippets over HTTP, but we are migrating to BlueHawk and generating the snippets locally, stored in the astro/src/generated-code-snippets. This folder should be altered only by the build scripts and not manually. The snippets are displayed with the LocalCode component. You can use entire files instead of snippets with LocalCode too, and don't need to annotate the source file to this. See the LocalCode component for details.

Here are the commands you can use with code snippets locally (in the astro folder):

• Test the examples: npm run test-code-examples (you need Docker installed)
• Validate snippets: npm run validate-code-snippets
• Generate snippets: npm run generate-code-snippets
• Start a local development server and generate snippets first: npm run dev
• Build the documentation: npm run build
• Start a local server and then browse to localhost:3000 npm run start

The following scripts are used in .github/workflows when pushing to GitHub:

• validate-code-snippets.yml — Validate the syntax of the annotations in each local code example.
• test-code-examples.yml — Runs the unit/integration tests for every local code example. Each repository must have a tests folder with a test.sh file that runs all its tests and returns a result. The test.sh script can be blank to return true with no tests. The tests workflow cannot use Github actions to install programming frameworks and versions, because each code example has different needs. Instead, each example uses Docker to run the tests with its own Docker image.
• export-code-examples.yml — Pushes each local code example to its readonly external repository. Each repository must have a repositoryUrl.txt file that says what URL (without the https:// and ending in .git) to export the files. Set repositoryUrl.txt to internal to skip export for self-contained guides. The Bluehawk annotations, repositoryUrl.txt file, and tests folder are removed before publishing.

How to migrate a repository from RemoteCode to local with BlueHhawk

• In the remote repository, create a main branch, make it the primary branch, delete all other branches
• Set access to readonly for all GitHub users other than documentation account
• Copy the contents of the repository into a new folder in astro/src/code-example-repositories
• Add a repositoryUrl.txt with the url of the remote (without https://)
• Add a tests folder with a test.sh file to run all tests using Docker (use node:26 if possible to avoid multiple images)
• Switch the repository annotation format from RemoteCode to Bluehawk in the source files (if you use the entire file you don't need annotations)
• Use LocalCode instead of RemoteCode in the accompanying article
• Run npm run validate-code-snippets && npm run generate-code-snippets to create the code snippets for display in the article
• Test the tests, snippet generation, and documentation build and create a pull request to the main FusionAuth branch

Build

To build the site:

1. Navigate into the astro directory, where the docs site lives:

   cd astro

2. Install dependencies:

   npm install

3. Run a local development instance of the site:

   npm run dev

   To view the site, use the link displayed at the end of build output. This development instance automatically rebuilds as you modify local files. Some parts of the site, including site search, won't run on the development instance. To preview those, try a full site build.

To run a full site build:

npm run start

This may take a minute or two. Output can be noisy, but do pay attention to the output from astro-link-validator, which runs at the very end of the build step. This check ensures that all internal links on the site point to valid URLs. For development convenience, this check doesn't fail the build, but you should always keep the broken link count at zero before merging into main.

Write Content

Always follow the content style guide found in CONTRIBUTING.md.

Lint

To check syntax across the entire site:

npm run lint

NOTE: Most of the site doesn't currently pass lint checks.

To check syntax in a specific file:

npm run lint -- src/components/BlogButton.astro

To skip linting when you inevitably include HTML somewhere in an MDX file, use the eslint-disable-next-line or eslint-disable-line:

{/* eslint-disable-next-line */}
<a href="https://www.fusionauth.io">FusionAuth</a>

Deploy

Deploying happens automatically via a GitHub action (one for content, another for redirects) whenever content merges into main. Dev server deployments have separate corresponding actions.

Redirects

src/redirects.json specifies our redirect rules. This file is published to s3 and read by a Lambda function that processes redirects for the site. When modifying the file:

• Keep items in alphabetical order!
• If you are moving a page around, update redirects.
• If you are adding a page that is an index page, update indexPages.
• If you are adding a new top level file or directory that's pulled from the S3 bucket, make sure you:
  • Add a behavior in CloudFront. You'll need to submit a PR in fusionauth-site-infra for this change.
  • If you are adding a top level file, add an entry to the s3Paths array.
  • If you are adding a top level directory, add an entry to the s3Prefixes array.