**Table of Contents**

- [Startup](#startup)
- [Modifying JavaScript](#modifying-javascript)
  - [Inline JavaScript/JSON comments](#inline-javascriptjson-comments)
  - [External JavaScript](#external-javascript)
- [How to pass the CI tests](#how-to-pass-the-ci-tests)
  - [Check commit messages](#check-commit-messages)
  - [Check the core functionality](#check-the-core-functionality)
  - [Check the SASS code style](#check-the-sass-code-style)

---

## Startup

Install [VS Code][vscode], [Dev Containers][extension], and [Docker][docker].

Next, fork this repository and then open VS Code to [clone your repo in container volume][clone-in-vol]. Wait a few minutes for Docker to create the container, and once everything is ready, you can start the Jekyll server in the VS Code terminal:

```console
./tools/run.sh
```

[vscode]: https://code.visualstudio.com/
[extension]: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers
[docker]: https://docs.docker.com/get-docker/
[clone-in-vol]: https://code.visualstudio.com/docs/devcontainers/containers#_quick-start-open-a-git-repository-or-github-pr-in-an-isolated-container-volume

## Modifying JavaScript

If your changes involve JavaScript, please read the following sections.

### Inline JavaScript/JSON comments

For inline JS (code between `<script>` and `</script>`) or JS / JSON file containing [Front Matter][front-matter], use `{%- comment -%}` and `{%- endcomment -%}` for comments instead of two slashes `//`. For example: `{%- comment -%} code comment message {%- endcomment -%}`. This is because in a _production_ environment, [jekyll-compress-html][html-compressor] compresses HTML files but does not recognize `//` correctly, which can break the HTML structure.

### External JavaScript

If you changed the files in the `_javascript/` directory, you need to rebuild the JS.  During development, real-time debugging can be performed with the following commands:

Firstly, start a Jekyll server:

```console
./tools/run.sh
```

And then open a new terminal session and run:

```console
npm run watch:js
```

When you are finished developing, press <kbd>ctrl</kbd> + <kbd>C</kbd> to end the `npm` process above, and then run the
`npm run build:js` command. The new compressed JS files will be exported to `assets/js/dist/`.

## How to pass the CI tests

This project has [CI][ci] enabled. To ensure your Pull Request passes the tests, please follow these guidelines.

### Check commit messages

Once you've run `npm install` in the root directory of the repository, [`commit-lint`][commitlint] is activated. Every commit you create will be checked to ensure it meets the requirements of [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).

> [!IMPORTANT]
> If you use a Node version manager and want to use Git hooks through Git GUIs, you might encounter a "command not found" error when committing your changes.
>
> For more information on the cause and solution, refer to the Husky docs: "[Node Version Managers and GUIs](https://typicode.github.io/husky/how-to.html#node-version-managers-and-guis)".

### Check the core functionality

```console
bash ./tools/test.sh
```

### Check the SASS code style

```console
npm test
```