Documentation

There are 2 types of the 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 .vortex/docs directory. This is removed when you install Vortex for a consumer site.

Local build

cd .vortex/docs
ahoy build

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

cd .vortex
ahoy update-docs

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

Check spelling and links

cd .vortex
ahoy test-docs

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

Publishing

An automated continuous integration build publishes this documentation.

• on tag, publishes to https://www.vortextemplate.com/docs/
• on every commit to a branch that contains release-docs string publishes to https://www.vortextemplate.com/docs/
• on every push to develop, publishes to development version of documentation https://vortex-docs.netlify.app
• on every push or tag, publishes to the temporary version of documentation with a link added to the PR as a comment.

Consumer site documentation

Vortex provides a scaffold of the consumer site documentation in the docs directory.

After Vortex is installed into the consumer site, these docs are intended to be used by the site maintainers and stay up-to-date with the project changes.

This documentation describes the what for the project:

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

When describing how to perform an operation, per-project documentation should reference the relevant page on https://www.vortextemplate.com/docs/ rather than duplicating instructions. This keeps project docs focused on decisions and configuration while leveraging the maintained Vortex documentation for operational details.