yann/chirpy-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chirpy.wiki

Browse Source
This commit is contained in:
yann 2025-05-28 08:32:13 +02:00
commit 7e3dc87c7d
8 changed files with 282 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored Normal file
View File

@ -0,0 +1 @@
.idea

80
Development-&-Test-Environments.md Normal file
View File

@ -0,0 +1,80 @@
**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
```

14
FAQ.md Normal file
View File

@ -0,0 +1,14 @@
**Table of Contents**
- [Why is there a blank page after the website is deployed to GitHub Pages?](#why-is-there-a-blank-page-after-the-website-is-deployed-to-github-pages)
- [Why isn't the website content updated immediately?](#why-isnt-the-website-content-updated-immediately)
---
## Why is there a blank page after the website is deployed to GitHub Pages?
Please take the time to read the [tutorial on deployment](https://chirpy.cotes.page/posts/getting-started/#deployment).
## Why isn't the website content updated immediately?
To load web pages offline, we used [PWA](https://web.dev/progressive-web-apps/) in this project. Every time you use a browser to visit your website, the local cache will be displayed to you first. At the same time, a background process will check for website updates and refresh the local cache. After that, you will be able to see the latest website contents; usually, this process takes tens of seconds to several minutes. If you want to see the latest content right away, please use the incognito mode of your browser.

16
Home.md Normal file
View File

@ -0,0 +1,16 @@
## Tutorial
- [Getting Started](https://chirpy.cotes.page/posts/getting-started/)
- [Customize the Favicon](https://chirpy.cotes.page/posts/customize-the-favicon/)
- [Writing a New Post](https://chirpy.cotes.page/posts/write-a-new-post/)
## Showcase
- [Text and Typography](https://chirpy.cotes.page/posts/text-and-typography/)
## Misc
- [FAQ](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/FAQ)
- [Upgrade Guide](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Upgrade-Guide)
- [Development](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Development-&-Test-Environments)
- [Maintenance](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Maintenance)

36
Maintenance.md Normal file
View File

@ -0,0 +1,36 @@
**Table of Contents**
- [Releasing a New Version](#releasing-a-new-version)
- [Managing the Hotfix Branches](#managing-the-hotfix-branches)
---
## Releasing a New Version
To release a new **Major** or **Minor** version, perform a *no fast-forward* merge from the `master` branch into the `production` branch.
To release a new **Patch** version, perform a *no fast-forward* merge from the `hotfix` branch into the `production` branch.
When GitHub Actions detects updates to the `production` branch, it will automatically trigger the release process.
> [!IMPORTANT]
> Please **do not enable** any check tools such as `Codacy Static Code Analysis` or `commitlint` under the repository’s branch protection rule *Require status checks to pass before merging*. Doing so will prevent GitHub Actions from pushing commits to the `master` branch, which will cause the automated release process to fail.
## Managing the Hotfix Branches
The `hotfix` branch naming format is `hotfix/<MAJOR>.<MINOR>.<PATCH>`, e.g. `hotfix/3.2.1`. It is a temporary branch with a life cycle:
1. Create a new `hotfix` branch from the `production` branch (on GitHub).
2. Commit the patch to the `hotfix` branch by:
1. Branching from `hotfix` and then committing patches to the new `patch` branch.
2. Creating a PR for the `patch` branch on GitHub, then squash merge it into the `hotfix` branch.
3. When hotfixes are done, create a PR for the `hotfix` branch and merge it into the `production` branch using the `--no-ff` option.
4. Delete this branch.
[front-matter]: https://jekyllrb.com/docs/front-matter/
[html-compressor]: https://github.com/penibelst/jekyll-compress-html
[ci]: https://en.wikipedia.org/wiki/Continuous_integration
[commitlint]: https://commitlint.js.org/

122
Upgrade-Guide.md Normal file
View File

@ -0,0 +1,122 @@
**Table of Contents**
- [Upgrading from Starter](#upgrading-from-starter)
- [Preparation](#preparation)
- [Adding Upstream](#adding-upstream)
- [Handling Submodule](#handling-submodule)
- [Fetch Updates](#fetch-updates)
- [Upgrade the Fork](#upgrade-the-fork)
- [Major Version Upgrades](#major-version-upgrades)
## Upgrading from Starter
If your website was created using [`chirpy-starter`][starter], follow these steps to update your repository.
### Preparation
The operations mentioned in this section only need to be performed once after cloning your repository locally.
#### Adding Upstream
```console
git remote add chirpy https://github.com/cotes2020/chirpy-starter.git
```
Verify the remote was added successfully:
```console
git remote -v
```
The output should include:
```log
chirpy https://github.com/cotes2020/chirpy-starter.git (fetch)
chirpy https://github.com/cotes2020/chirpy-starter.git (push)
```
#### Handling Submodule
If your workflow does not require the submodule `assets/lib`, run command:
```console
git config submodule.assets/lib.ignore all
```
This prevents the submodule from pulling files and taking up local disk space.
### Fetch Updates
The following steps need to be performed for each update.
1. Fetch all tags from upstream:
```console
git fetch chirpy --tags
```
2. Merge the latest tag from upstream into your local branch. For example, to merge tag `vX.Y.Z`, run:
```console
git merge vX.Y.Z --squash --allow-unrelated-histories
```
3. If the list of conflicting files includes the submodule `assets/lib`:
- If you do not want to use the submodule, execute:
```console
git restore --staged assets/lib
```
- If you have already initialized and enabled the submodule, follow the output hint:
```
hint: - go to submodule (assets/lib), and either merge commit <submodule_commit_hash>
```
Record the `submodule_commit_hash` and update the local submodule:
```console
git -C assets/lib merge <submodule_commit_hash>
```
4. Resolve any remaining file conflicts manually. Keep any custom modifications if needed.
5. Once conflicts are resolved, create a new commit to save the upgrade:
```console
git add . && git commit -m "chore: upgrade to X.Y.Z"
```
6. Update the local theme gems:
```console
bundle update
```
## Upgrade the Fork
If you forked from the source project (there will be `gemspec` in the `Gemfile` of your site), merge the [latest upstream tags][latest-tag] into your Jekyll site to complete the upgrade.
The merge may conflict with your local modifications. Be patient and careful when resolving these conflicts.
JS distribution files have been removed since [`v5.6.0`][v5.6.0], and Bootstrap CSS has been lean since [`v7.0.0`][v7.0.0]. For future upgrades, compile the CSS/JS files yourself:
```console
npm run build
```
Then add them to your repository files:
```console
git add assets/js/dist _sass/vendors -f
```
## Major Version Upgrades
When upgrading to a **Major** version, read the [release notes][release-notes] for that version to understand any changes in project configuration.
[starter]: https://github.com/cotes2020/chirpy-starter
[latest-tag]: https://github.com/cotes2020/jekyll-theme-chirpy/tags
[v7.0.0]: https://github.com/cotes2020/jekyll-theme-chirpy/releases/tag/v7.0.0
[v5.6.0]: https://github.com/cotes2020/jekyll-theme-chirpy/releases/tag/v5.6.0
[release-notes]: https://github.com/cotes2020/jekyll-theme-chirpy/releases

1
_Footer.md Normal file
View File

@ -0,0 +1 @@
[:pencil: Helps improve this page](https://github.com/cotes2020/jekyll-theme-chirpy/discussions/new?category=general)

12
_Sidebar.md Normal file
View File

@ -0,0 +1,12 @@
- [**Back to Home**](https://github.com/cotes2020/jekyll-theme-chirpy/wiki)
- **Tutorial**
- [Getting Started](https://chirpy.cotes.page/posts/getting-started/)
- [Customize the Favicon](https://chirpy.cotes.page/posts/customize-the-favicon/)
- [Writing a New Post](https://chirpy.cotes.page/posts/write-a-new-post/)
- **Showcase**
- [Text and Typography](https://chirpy.cotes.page/posts/text-and-typography/)
- **Misc**
- [FAQ](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/FAQ)
- [Upgrade Guide](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Upgrade-Guide)
- [Development](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Development-&-Test-Environments)
- [Maintenance](https://github.com/cotes2020/jekyll-theme-chirpy/wiki/Maintenance)