Skip to main content
Version: v1

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.

Combined site​

The published site serves two majors at once. The branch that ships the current major - selected by the VORTEX_CURRENT_MAJOR repository variable, default 1 - is snapshotted as the default version at /docs, and the other major's {N}.x branch content is served at /docs/v{N}.

Each branch writes its content against the bare /docs mount, so an absolute link such as /docs/tools/behat points at the current major. When that content is assembled under /docs/v{N}, those links are re-pointed at the major they were written for, and a link that already names a version is left alone. Write links the way they read on their own branch.

Static assets work the same way. Both majors record their own demo videos and diagrams under the same static/img names, so the other major's static/ is served from /v{N} and its asset references are re-pointed to match. Each version therefore shows its own screenshots and recordings. Reference assets the way they read on their own branch, from the bare /img.

To build and browse the combined site locally:

cd .vortex

# Build both majors into 'docs_combined'. Fails on broken internal links.
ahoy docs-combined

# Serve the result on port 4000. Pass a port to override.
ahoy docs-combined-serve

Everything the build writes stays inside docs_combined, a git-ignored copy of docs that is rebuilt from scratch on every run and safe to delete at any time. The tracked docs directory is only ever read, so ahoy docs and ahoy build-docs keep working on this branch's documentation alone.

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.