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 (opens in a new tab).

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

Overview

The Spice docs are built with Docusaurus (opens in a new tab) and hosted on Cloudflare Pages (opens in a new tab). The Deployment (opens in a new tab) section describes how changes are published.

The website (opens in a new tab) directory contains the Docusaurus project, markdown files, and theme configurations.

Prerequisites

• Node.js (opens in a new tab) 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

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

3. Change to website directory:

cd ./docs/website

cd ./docs/website

4. Install npm packages:

npm install

npm install

Run Local Server

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

npm start

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
   

   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
   

   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 (opens in a new tab)).

Deployment

The build_and_publish (opens in a new tab) workflow builds the site in GitHub Actions and uploads website/build to the spiceai-org-website Cloudflare Pages project with wrangler pages deploy (opens in a new tab). A push to trunk deploys to production at spiceai.org (opens in a new tab) 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 (opens in a new tab), 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 (opens in a new tab) 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 (opens in a new tab) 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 (opens in a new tab) 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.