Spectro Cloud Documentation

Welcome to the Spectro Cloud documentation repository. This repository contains the source for docs.spectrocloud.com.

The PaletteAI product has its own documentation site. Refer to the PaletteAI documentation.

Use this README as a quick start for contributing. For deeper guidance, see the contributor guides linked below.

For internal Spectro Cloud users, review the contributions section of the Documentation & Education team's home page.

Quick Start

The recommended local development path uses Docker.

1. Install the required software listed in the Local Development guide.

2. Initialize the repository.

   make init
   

3. (Optional) To preview pack pages locally, add your Palette API key to the .env file and change DISABLE_PACKS_INTEGRATIONS to false. Without these values, the server still starts and pack pages redirect to the Integrations page.

   PALETTE_API_KEY="<your-palette-api-key>"
   DISABLE_PACKS_INTEGRATIONS=false
   

   Replace <your-palette-api-key> with your Palette API key. Refer to the Create API Key guide to learn how to create one.

4. Start the Docker-based local development server.

   make docker-start
   

5. Open http://localhost:9000 to view the documentation website.

For the non-Docker setup, refer to Local Development.

Make Documentation Changes

Update your local master branch and create a branch for your changes.

git checkout master
git pull
git checkout -b <branch_name>

Dependencies change often, so refresh your local Node.js modules to match package-lock.json.

make ci-local

Most documentation pages are in the docs/docs-content folder. Products that release on their own schedule live in docs/products instead, because they are versioned independently of Palette. Refer to Product Documentation Versions for how that works. Make changes to the relevant Markdown or MDX files, then preview them locally.

make start

If you use the Docker setup, run make docker-start instead of make start. The Docker image installs dependencies from package-lock.json each time it builds.

When your changes are ready, stage and commit them.

git add -A && git commit -m "docs: your commit message here"

Use the docs: commit prefix for regular documentation changes. Avoid feat:, fix:, perf:, and other semantic-release prefixes unless you intentionally need to trigger a version change.

Validate Your Changes

Run the checks that match your change before opening a pull request.

Check	Command	More information
Writing style	make check-writing	Checks and CI
Formatting	make format-check	Checks and CI

The content in this repository requires approval from the documentation team. Approval rules are defined in CODEOWNERS.

Contributor Guides

Guide	Use it for
Local Development	Prerequisites, Docker setup, non-Docker setup, and local environment variables.
Authoring Content	Creating pages, organizing sidebars, tutorials, and reviewer guidance.
Markdown and MDX	Links, images, redirects, code blocks, and admonitions.
Components	Tabs, videos, tooltips, partials, badges, cards, and Palette/VerteX URL helpers.
Generated Content and Integrations	API docs, security bulletins, packs, cached generated data, and the Kapa widget.
Checks and CI	Netlify previews, Vale, Prettier, spellcheck, and build exit codes.
Release Process	Release branches, unreleased banners, Palette release automation, and release commands.
Style Guide	Spectro Cloud documentation style, grammar, formatting, and usage guidance.

Repository References

File or directory	Description
docs/docs-content	Main documentation content.
docs/api-content	API documentation content generated from OpenAPI specs.
docs/products	Independently versioned product documentation.
productDocs.js	Registry of independently versioned products.
<product>_versioned_docs	Frozen copies of a product's earlier documentation versions.
_partials	Reusable MDX partials.
static/assets/docs/images	Documentation image assets.
CODEOWNERS	Pull request ownership and approval rules.
Makefile	Local development, validation, and release helper commands.

Related GitHub Repositories

Repository	Use it for
spectrocloud/librarium	Spectro Cloud documentation source.
spectrocloud/spectro-vale-pkg	Spectro Cloud Vale style rules.
spectrocloud/tutorials	Tutorial source and supporting examples.
spectrocloud/docs-assignments	Documentation assignment tracking.
spectrocloud/docusaurus-versioning-template	Historical Docusaurus versioning reference and demo template.
spectrocloud/hello-universe	Hello Universe sample application.
spectrocloud/hello-universe-api	Hello Universe API service.
spectrocloud/hello-universe-db	Hello Universe database service.