Skip to main content

Documentation

These docs live in .eddy/docs, a Docusaurus site with its pages in content/. Like the rest of .eddy, they never reach a generated project.

Working locally​

The site is an npm project of its own. Run these from .eddy/docs:

npm install                  # Install the dependencies
npm start                    # Serve the site locally, reloading on every change
npm run build                # Build the static site into build/
npm run serve                # Serve the built site
npm test                     # Run the component tests and the spell check
npm run spellcheck           # Run only the spell check
npm run test:accessibility   # Check the built site for accessibility issues

npm start and npm run build first copy the social preview card from .eddy/assets into static/img, where git ignores it.

npm run test:accessibility checks the site in build/, so run npm run build first. It drives a browser through Playwright, which needs its own copy of Chromium: npx playwright install chromium downloads it once.

Writing pages​

  • 1 topic per page. The sidebar follows the folder tree of content/, ordered by the sidebar_position in each page's front matter. A folder's README.mdx is its index page.

  • Link by file. Link to another page by its relative path, such as [Webserver](../development/webserver.mdx#how-the-port-is-picked). The build checks every link and anchor, and fails on a broken one.

  • Commands for every setup. A generated project has Make, Ahoy, both or neither, so show commands with the CommandTabs component. It renders a tab per setup, and every tab set on the site follows the reader's last choice:

    import CommandTabs from '@site/src/components/CommandTabs';

    <CommandTabs
      make={`make build`}
      ahoy={`ahoy build`}
      none={`vendor/bin/eddy-assemble`}
    />

    Leave out a prop when a setup has no equivalent command, and its tab goes with it.

  • Images. The animated demos stay in .eddy/assets, and pages import them by relative path, such as ![Building the site](../../../assets/build.svg), so the build fails when one goes missing. Put any other image in static/img.

  • Diagrams. A mermaid code block renders as a Mermaid diagram.

  • Spelling. CSpell checks the pages in US English with the words in cspell.json. Add a word the docs use in several places there, and a word only 1 page uses to that page, as {/* cspell:ignore word */}.

Accessibility​

The site aims for WCAG 2.2 level AA in both color modes. npm run test:accessibility runs axe on every page of the build, in light and dark mode, at a desktop width and a phone width, against the WCAG A and AA rules. It also opens the search dropdown, the mobile menu and an animated demo, and checks how they behave from the keyboard. Automated checks catch a good share of problems, not all of them, so the writing still needs the care described below.

Some of it is handled for you, so a page needs no extra markup:

  • Links in page text are underlined, because color alone doesn't set a link apart from the text around it.
  • Text colors reach at least 4.5:1 against their background. The light-mode blue is #006c99, a darker shade of the #009cde logo blue, which only reaches about 3:1 on white. The code block colors live in src/codeThemes.js, and a unit test checks every token color of both themes.
  • An animated SVG added with Markdown image syntax gets a Pause animation button, and it starts paused when the reader's system asks for reduced motion.
  • A table wider than the page takes keyboard focus, so it scrolls with ← and →.
  • The mobile menu keeps keyboard focus inside while it's open and closes on Esc, and the search box gets the ARIA attributes that its autocomplete widget leaves out. Both fixes live in src/theme/, so check them when Docusaurus or the search plugin changes its markup.

The rest is down to the writing:

  • Give every image alt text that says what it shows.
  • Keep heading levels in order, without skipping one.
  • Make link text say where it goes, such as Webserver rather than "here".

Checks on every pull request​

The eddy-test-docs job of the Test Eddy workflow installs the dependencies, builds the site, runs npm test and then npm run test:accessibility. A broken link or anchor, a failing component test, an unknown word or an accessibility violation fails the job, and a failed check skips the Netlify deployment below.

The development site and previews​

The same job deploys the built site to Netlify: every push to main updates the development site, and every pull request gets a preview of its own, linked in a comment on the pull request. The deployment runs only when the NETLIFY_SITE_ID and NETLIFY_AUTH_TOKEN repository secrets are set, so a pull request from a fork still builds and tests the docs without one.

These builds show "development" as the version in the footer, and search engines don't index them.

Publishing​

.github/workflows/eddy-release-docs.yml publishes the docs to eddy.drevops.com on GitHub Pages:

  • on every release tag, with the tag as the version;
  • on a manual run of the Release Eddy docs workflow from Actions, with the version you type.

The repository's GitHub Pages source must be GitHub Actions, and the github-pages environment must let the tag or the branch you run from deploy.

The workflow reads the site URL and base path from the GitHub Pages settings, so a custom domain needs no change to the code. The published site links to the address it was built for, so run the workflow again after you change the domain. Only these release builds report to Google Analytics, show the release in the footer and let search engines index the pages.