Spice.ai OSS Documentation

This repository contains the source files for the Spice.ai OSS documentation website.

To view the published documentation, visit https://docs.spiceai.org.

To contribute to the documentation, follow the instructions below to set up a local development environment.

Overview

The Spice docs are built with Docusaurus and hosted on Cloudflare Pages. The Deployment section describes how changes are published.

The website directory contains the Docusaurus project, markdown files, and theme configurations.

Prerequisites

• Node.js 24 or later
• npm (included with Node.js)

Docusaurus is installed as a project dependency and does not need to be installed globally.

Environment setup

1. Ensure pre-requisites are installed
2. Clone this repository

git clone https://github.com/spiceai/docs.git

3. Change to website directory:

cd ./docs/website

4. Install npm packages:

npm install

Run Local Server

1. Ensure you are in the website directory.
2. Start the development server:

npm start

3. Open http://localhost:3000/ in a browser. The local documentation site should appear, and changes to markdown files are reflected automatically.

Contributing to the Docs

1. Fork this repository to your GitHub account.

2. Clone your fork and create a new branch:

   git checkout -b my-docs-update

3. Make changes to the markdown files in website/docs/.

4. Commit and push your changes:

   git add .
   git commit -m "docs: describe your change"
   git push origin my-docs-update

5. Open a pull request from your branch to the trunk branch of the upstream repository.

6. GitHub Actions builds the pull request. For a pull request from a branch in this repository, it also deploys a preview site and links it in a pull request comment. Pull requests from forks are built but not deployed (see Deployment).

Deployment

The build_and_publish workflow builds the site in GitHub Actions and uploads website/build to the spiceai-org-website Cloudflare Pages project with wrangler pages deploy. A push to trunk deploys to production at spiceai.org and starts an Algolia search reindex. For a pull request, the workflow deploys a preview and comments its URL on the pull request. Pull requests from forks are built but not deployed, because GitHub does not pass secrets, such as the Cloudflare API token, to workflows triggered from a fork.

The repository is also connected to the Cloudflare Pages project, but Cloudflare's automatic Git deployments are turned off (the project's deployments_enabled setting is false), so GitHub Actions is the only deploy path. If automatic deployments are turned back on, every Cloudflare build fails with ENOENT: no such file or directory, open '/opt/buildhome/repo/package.json', because the project's root directory is empty and the Docusaurus project is in website/.

To build in Cloudflare instead, set the project's root directory to website and its NODE_VERSION environment variable to 24, and turn automatic Git deployments back on. Then change the workflow:

• Remove the deploy step, so each push deploys once.
• Remove the pull request comment step, which posts the deploy step's URL.
• Start the Algolia reindex only after Cloudflare finishes a successful production deployment. Without the deploy step, the current reindex step would run right after the workflow's build, before Cloudflare publishes the new site.