81 lines
3.2 KiB
Markdown
81 lines
3.2 KiB
Markdown
**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
|
|
```
|
|
|