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 start and npm run build first copy the social preview card from .eddy/assets into static/img, where git ignores it.

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 */}.

Checks on every pull request​

The eddy-test-docs job of the Test Eddy workflow installs the dependencies, builds the site and runs npm test. A broken link or anchor, a failing component test or an unknown word fails the job.

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.