Skip to main content

Documentation

There are 2 types of documentation that Vortex provides:

  1. Vortex template documentation (this site) - generic information on how to perform operations, applicable to all projects built with Vortex. Deployed to https://www.vortextemplate.com/docs/
  2. Per-project documentation - project-specific information on what the project does, distributed in the docs/ directory when Vortex is installed.

The key relationship: per-project documentation describes what (coding standards, testing requirements, release configuration) while referencing the Vortex documentation for how to perform specific operations.

www.vortextemplate.com​

This documentation provides generic "how-to" guides suitable for any project using the Vortex template. It covers tooling, automation, and operations that are common across all Vortex-based projects.

The source is written in Markdown and located in the .vortex/docs directory. This is removed when you install Vortex for a consumer site.

Local build​

Run the docs commands from the .vortex/ directory:

cd .vortex

# Start the local development server with live reload.
ahoy docs

# Build the production site. The build fails on broken internal links.
ahoy build-docs

Parts of the documentation are generated automatically from the codebase. To update them, run:

cd .vortex
ahoy update-docs

If you have the documentation site running locally, the content changes will be available immediately.

Lint, spellcheck and test​

cd .vortex

# Lint the Markdown and check American English spelling.
ahoy lint-docs

# Run the Jest component tests and the spellcheck.
ahoy test-docs

If required, add spelling exclusions to the .vortex/docs/cspell.json file.

Internal links are not checked by these commands - the Docusaurus build is the link checker, failing on broken internal links (ahoy build-docs).

Documentation videos​

The 6 terminal demo videos embedded in the docs are regenerated with ahoy update-videos [names] from .vortex/ - see Installer > Installer video for the pipeline.

Publishing​

Automated continuous integration builds publish this documentation:

Consumer site documentation​

Vortex ships a scaffold of consumer site documentation in the docs directory. It is installed into every consumer site, where the site maintainers keep it up-to-date with their project.

The scaffold covers the what of a project:

  • Coding standards and agreements specific to the project
  • Testing requirements and configuration
  • Release and deployment configuration
  • Project-specific procedures and decisions

The scaffold references this site for the how of each operation instead of duplicating instructions - so when maintaining the template, keep the scaffold pointing at the right pages here, and keep the how content on this site rather than in the shipped docs/ files.