Development & Test Environments

Table of Contents

• Startup
• Modifying JavaScript
  • Inline JavaScript/JSON comments
  • External JavaScript
• How to pass the CI tests
  • Check commit messages
  • Check the core functionality
  • Check the SASS code style

---

Startup

Install VS Code, Dev Containers, and Docker.

Next, fork this repository and then open VS Code to clone your repo in container volume. 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:

./tools/run.sh

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:

./tools/run.sh

And then open a new terminal session and run:

npm run watch:js

When you are finished developing, press ctrl + C 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.

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".

Check the core functionality

bash ./tools/test.sh

Check the SASS code style

npm test