Documentation

This page is for contributors who write or change the Vortex documentation. It explains how the 2 kinds of documentation divide the work, and covers building, checking and publishing this site, and recording its demo videos.

Vortex has 2 kinds of documentation, split by the question each one answers:

• Vortex template documentation (this site) - generic information on how to perform operations, true for every project built with Vortex. It's published at vortextemplate.com.
• Per-project documentation - information on what applies to 1 project, shipped in the docs/ directory of each new site.

The per-project files record a project's own decisions, such as its testing conventions, its CI and hosting setup and its release configuration. They link here for how to carry each decision out, so the how-to lives in 1 place and a fix to it reaches every project.

www.vortextemplate.com

This site holds the generic how-to guides for every project built from the Vortex template: the tooling, the automation and the operations those projects share.

The site is built with Docusaurus and written in MDX, which is Markdown with React components. Its source lives in the .vortex/docs directory. The installer removes .vortex/ from every consumer site, so the documentation source never reaches a consumer site.

Local build

To preview the site with live reload or build it for production, run these commands:

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

Both commands install the site's dependencies first when node_modules is missing.

The variables table at the end of Variables comes from the code itself. ahoy update-docs runs Shellvar in a Docker container, so Docker must be running. Shellvar extracts the variables and their descriptions from these sources:

• .env and .env.local.example
• The tooling scripts in .vortex/tooling/src/
• The scripts in scripts/
• The stub files in .vortex/docs/.utils/variables/extra/, which describe the variables the other sources leave out

The stub files cover the variables commented out in .env, and the ones that the hosting platforms, docker-compose.yml and the CI configuration set. The command rewrites the page from its ## Variables list heading down. To regenerate the table, run these commands:

cd .vortex
ahoy update-docs

The documentation workflows run the same extraction and fail when its result differs from the committed page, so commit the result together with the change that caused it. A running ahoy docs server picks up the new content straight away.

Lint, spellcheck and test

To check the documentation, run these commands:

cd .vortex

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

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

ahoy lint-docs also checks the site code in src/ and the Jest tests in tests/ with ESLint and Prettier. ahoy lint-docs-fix applies the fixes that ESLint, Prettier and markdownlint can make on their own. ahoy test-docs installs the site's dependencies when they're missing, and ahoy lint-docs doesn't, so on a fresh checkout, run ahoy install first.

When cspell rejects a correct word, add it to the words list in .vortex/docs/cspell.json.

Only the Docusaurus build checks internal links: ahoy build-docs fails on a broken link. A link to a missing anchor only prints a warning, so look for those in the build output.

Lines can't run past 76 characters, and markdownlint enforces the limit. Code blocks, tables and headings are exempt, and so is a line that holds only 1 unbroken token, such as a long URL. Code inside a JSX element such as <TabItem> still counts, so split a long command there with \.

Prose style

Vale checks the prose of every page against the house style. yarn install in .vortex/docs installs the Vale binary from the Vale npm package, a development dependency of the site. Vale reports 2 levels of alert: errors fail the run and the continuous integration build, and warnings are advisory.

The house style writes every number as a digit, such as 1 file or 0 errors. Ordinals in prose, such as the first step, and fixed expressions, such as one-off, stay words. Lists take no serial comma: install, configure and run. Each sentence carries 1 idea in 30 words or fewer.

Errors flag the following:

• Product names in the wrong case
• Headings that aren't in sentence case
• Phrases that take a contraction, such as do not
• Filenames and UPPER_SNAKE_CASE names outside inline code
• Vortex without bold in prose
• The numbers 0 and 2 to 10 written as words, and ordinals written as numerals, such as 1st
• Em dashes and en dashes
• e.g. and i.e.
• Marketing adjectives, such as powerful
• Condescending words, such as simply
• Throat-clearing phrases, such as keep in mind
• Stacked hedges, such as might possibly
• Vague link text, such as click here
• Terms from the Google word list, such as above instead of preceding
• Hyphens after -ly adverbs
• Sentences that start with There is or There are
• Repeated words
• Exclamation marks, doubled spaces and periods inside acronyms
• Gendered pronouns, such as he/she, and gender-biased terms
• Optional plurals, such as file(s)
• Units without a space after the number, such as 10MB
• Internet slang
• Times in a format other than 9 AM, and dates in a format other than July 31, 2016

Warnings flag the following:

• A serial comma before the last and or or of a list
• The word one where it counts something
• Sentences longer than 30 words
• Wordy phrases, such as a number of
• Weasel words, such as very
• The word will
• A period at the end of a heading
• Ellipses
• from or between in front of a number range
• Some British spellings

Vale's own spell check is off, because cspell does that job.

The rules come from 4 places:

• The Google and write-good style packages. They're pinned by release URL in .vortex/docs/.vale.ini, and vale sync downloads them when you run yarn install. ThereIs is the only write-good rule that runs on its own. 2 house rules extend the word lists of the write-good rules Weasel and TooWordy.
• Vale's built-in Vale style, which flags repeated words and applies the vocabulary.
• The house style in .vortex/docs/.vale/Vortex/, with 1 small YAML file for each rule. A rule that adjusts a Google rule inherits it with extends and edits its word lists. .vale.ini then switches the original Google rule off.
• The vocabulary in .vortex/docs/.vale/config/vocabularies/Vortex/accept.txt, which lists product names with their exact casing.

To lint a single page while you write, run these commands:

cd .vortex/docs
yarn lint-prose --glob='content/installation.mdx'

When a rule blocks a correct sentence, fix the rule instead of silencing the alert:

• For a product name, add it to the vocabulary.
• For a proper noun in a heading, add it to Headings.yml.
• For a word that the rule matches by mistake, remove it from the rule's list.

tests/unit/vale-rules.test.js runs Vale over a valid and an invalid fixture page in tests/fixtures/vale/. It compares the alerts with a list in the test, so update the fixtures and that list together with the rule.

Vale skips block quotes, because they quote upstream projects verbatim. It also skips the generated table in development/variables.mdx, but it lints the prose before the table. MDX import statements and JSX <li> items are skipped too, so their text doesn't merge into 1 long sentence.

Documentation videos

The docs embed 9 terminal demo videos. The following table lists each video and what it records:

Video	Records
installer	The installer, answered by an Expect script
build	ahoy build
provision	ahoy provision
lint	ahoy lint
test	ahoy test
test-bdd	ahoy test-bdd
info	ahoy info
doctor	ahoy doctor
doctor-info	ahoy doctor info

Run ahoy update-videos from .vortex/ to re-record every video, or pass the video names, separated by spaces or commas, to record a subset. For each video, the command writes <name>.json, <name>.svg and <name>.png to .vortex/docs/static/img/.

A default run wipes the workspace in .artifacts/tmp/videos-workspace/, builds the installer and installs a fresh project there. Every video except installer needs that project built, so the run builds it once. Add --keep to reuse the existing workspace and its running Docker stack and skip that bootstrap. A --keep run can't re-record installer.

The recorder decodes every recording to text at .artifacts/videos/<name>.txt. It doesn't render a recording whose output reports an error, a warning or a failure, so every video shows commands that succeed. No flag overrides that check: fix the command that printed the output, then record again.

Recording needs these commands on your PATH:

• asciinema, expect, php, composer, node and npx for every video
• ahoy and docker for every video except installer

The command doesn't commit anything, so review the diff under .vortex/docs/static/img/ and commit it yourself. For the recording pipeline, see Installer > Installer video.

Combined site

The published site serves 2 majors at once. The VORTEX_CURRENT_MAJOR repository variable picks the current major, and it defaults to 1. The build serves a snapshot of that major's branch, main, as the default version at /docs, and the other major's {N}.x branch at /docs/v{N}.

The other major's pages carry a banner that reads "unreleased" when that major is newer than the current major, and "unmaintained" when it's older. /docs/v{current} redirects to /docs.

The content on each branch links against the bare /docs mount, so an absolute link such as /docs/development/testing/behat points at the current major. The build moves the other major's content under /docs/v{N} and re-points those links at the major they were written for. A link that already names a version keeps its target.

The build rewrites only Markdown link targets, so write an absolute docs link as [label](/docs/...), never inside a JSX attribute. Write every other link the way it reads on its own branch.

Static assets work the same way. Both majors record their own demo videos and diagrams under the same static/img names. The build serves the other major's static/ from /v{N} and re-points its asset references to match, in Markdown targets and JSX attribute values alike. Each version then 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, run these commands:

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

The build writes only inside docs_combined, a git-ignored copy of docs that every run rebuilds from scratch and that you can delete at any time. The build only reads the tracked docs directory, so ahoy docs and ahoy build-docs keep working on this branch's documentation alone.

The build treats this checkout as the current major, unless VORTEX_DOCS_MAJOR names the other major. It fetches the other branch from origin, so it needs network access.

Publish the site

Continuous integration publishes this documentation from 2 workflows, and both build the combined site.

Vortex - Release docs (.github/workflows/vortex-release.yml) publishes the live site to GitHub Pages. The same run builds the installer and publishes it at /install. The workflow runs in these cases:

• On every tag
• On every push to a branch whose name contains release-docs or release-installer
• When you run it by hand

Vortex - Test docs (.github/workflows/vortex-test-docs.yml) runs after the Vortex - Test installer workflow succeeds. On the 2.x branch, it runs after Vortex - Test CLI instead. It publishes only when its own documentation checks pass:

• A push to main goes to the development site on Netlify.
• Any other branch gets a draft preview. When the branch has a pull request from this repository, the workflow posts the preview link on it as a comment.

A release-docs or release-installer branch publishes to the live site, so until the next publish, everyone gets that branch's documentation and installer.

Consumer site documentation

Vortex ships a scaffold of consumer site documentation in the docs directory. The installer copies it into each consumer site, unless you answer no to its Preserve project documentation? question. From then on, the site's maintainers keep it current.

The scaffold covers what applies to each project, with 1 file per topic, and README.md indexes them:

• testing.md - the testing conventions for PHPUnit and Behat
• ci.md - the CI provider and the project's CI configuration
• deployment.md - the hosting provider and the deployment rules
• releasing.md - the release outcome and the version scheme
• faqs.md - project-specific FAQs

For how to perform each operation, the scaffold links to this site. When you maintain the template, keep those links pointing at the right pages. Keep the how-to content on this site, out of the shipped docs/ files.