Handbook

The Bloom Works employee handbook, with our policies and norms.

Run Instructions

This requires Docker to be installed and running

1. Build the container: docker build -t bloom-works/handbook .
2. Start the server: docker run -it --rm -p "8080:8080" bloom-works/handbook
3. View the site in your browser at http://localhost:8080

Developer Setup

Docker Version

This sets up the site with a consistent runtime environment, and requires Docker to be installed and running.

1. Navigate to the base of this repo
2. Build the container: docker build -t bloom-works/handbook .
3. Start a terminal inside the container: docker run -it --rm -p "8080:8080" -v "$PWD:/app" bloom-works/handbook bash
4. Install dependencies (first time only or when package.json changes): npm install
5. Start server: npm run serve
6. View the site in your browser at http://localhost:8080

From here, changes to files locally will rebuild the site.

Local Version

This uses whatever NPM and Node version you have installed on your machine, and might use fewer system resources than the Docker install (i.e. better for lower powered machines). If something is not working using this setup, use the Docker version to see if the problem exists there.

1. Navigate to the base of this repo
2. Install dependencies (first time only or when package.json changes): npm install
3. Start server: npm run serve
4. View the site in your browser at http://localhost:8080

From here, changes to files will rebuild the site.

Editing Instructions

Adding a Section

To add a new section to the site:

1. Add a new Markdown file to the sections folder (example: sections/my-new-section.md)
2. At the top of the file, add two lines with --- and between those two lines put:
   • layout: layouts/section
   • title: My New Section's Title
3. Add content below the second ---
4. Add the base of the file name into the _data/table_of_contents.json file in the desired order. For example, if you section is called super-important.md, then you would add the "super-important" (no .md) into the _data/table_of_contents.json.

Feel free to look at any of the existing sections as a starting point.

Adding an image

If you need to embed an image in a Handbook page, put the image file in the /img folder. The resulting URL pattern will be: /img/FILENAME.suffix.

Checking code before PR

Running Linters

1. Navigate to the base of this repo
2. Run sh ./ci/linter.sh

CSS -- Stylelint Docs

1. If there are errors, npx stylelint --fix "**/*.css" will perform a dry-run of fixing all errors and those errors will not be saved. Then npx eslint --ext .js --fix [file or directory here] will fix and save all errors.

JS -- ESLint Docs

1. If there are errors, npx eslint --ext .js --fix-dry-run [file or directory here] will perform a dry-run of fixing all errors and those errors will not be saved. Then npx eslint --ext .js --fix [file or directory here] will fix and save all errors.

Nunjucks -- djLint Docs

1. From the base of this repo run djlint ./ -e .njk --profile=nunjucks to only run djlint. Manually fix errors.

Running Node Tests

We are using Playwright Tests to accomodate our testing needs for this project on destop and mobile.

1. From the base of this repo run npx playwright test for the command line output or npx playwright test --ui to open the tests in UI mode.

Running Accessibility Tests

We are using Cypress and Axe core as our testing framework and engine for our accessibility tests.

1. Start your local server and make sure it's running at http://localhost:8080
2. Navigate to the base of this repo and run npx cypress run for tests to execute in the command line. To execute tests in Cypress' UI window, run npx cypress open and select E2E testing.
3. We have added functionality that will print an error table in the command line on test execution. This table includes the name and description of the error along with a helpUrl containing a URL where more information on how to fix that particular error can be found. Additionally, you can visit the official axe-core rules github to view the different axe-core rule descriptions.
4. Cypress captures snapshots at the time of test execution, these can be viewed by navigating to the cypress/screenshots folder.

**Additional Notes on Cypress Testing for Local Development

• During local development, it is important to restart your server if you're making code or package changes while http://localhost:8080 is still running. This will ensure the Cypress tests are running and passing correctly in your local environment.
• If you are running Cypress tests in Docker and/or on a virtual machine, there are additional dependencies you will need to install depending on what type of environment you have.
• If you are running Docker on your machine and get an error that Cypress is not installed and that it cannot find the cypress file at /root/.cache/Cypress/12.17.1/Cypress, this could be a permissions issue and you would run node_modules/.bin/cypress install inside of the Docker container to install Cypress.