asandikci.com/web
1
0
Fork 0
Code Issues 5 Pull requests Projects Releases Packages Wiki Activity Actions

docs: move the development guide to README (#900)

Browse source
This commit is contained in:
Cotes Chung 2023-03-01 08:23:08 +08:00
parent fe82cea576
commit 09121c1d11
No known key found for this signature in database
GPG key ID: 0D9E54843167A808
2 changed files with 83 additions and 103 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

65
.github/CONTRIBUTING.md vendored
View file

@ -1,66 +1,55 @@
# How to Contribute # How to Contribute
We'd like to thank you for sparing time to improve this project! Here are some guidelines for contributing： :tada: We really appreciate you taking the time to improve this project! :tada:
To ensure that the blog design is not confused, this project does not accept suggestions for design changes, such as color scheme, fonts, typography, etc. If your request is about an enhancement, it is recommended to first submit a [_Feature Request_](https://github.com/cotes2020/jekyll-theme-chirpy/issues/new?labels=enhancement&template=feature_request.md) issue to discuss whether your idea fits the project. To ensure that the blog design is not confusing, this project does not accept
suggestions for design changes, such as color scheme, fonts, typography, etc.
If your request is about an enhancement, it is recommended to first submit a
[Feature Request][pr-issue] issue to discuss whether your idea fits the project.
## Basic Process Basically, you can follow these steps to complete the contribution.
Generally, contribute to the project by:
1. Fork this project on GitHub and clone it locally. 1. Fork this project on GitHub and clone it locally.
2. Create a new branch from the default branch and give it a descriptive name (format: `feature/<add-new-feat>` / `fix/<fix-a-bug>`). 2. Create a new branch from the default branch and give it a descriptive name
3. After completing the development, submit a new _Pull Request_. Note that the commit message must follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), otherwise it will fail the PR check. (format: `feature/<add-new-feat>` or `fix/<fix-a-bug>`).
3. After completing development, create a [Conventional Commit][cc] with git.
(See also: ["Verify the commits"](#verify-the-commits))
4. Create a [Pull Request][gh-pr].
## Modifying JavaScript ## Make sure you can pass the CI tests
If your contribution involves JavaScript modification, please read the following sections. This project has [CI][ci] turned on. In order for your [PR][gh-pr] to pass the test,
please read the following.
### Inline Scripts
If you need to add comments to the inline JavaScript (the code between the HTML tags `<script>` and `</script>`), please use `/* */` instead of two slashes `//`. Because the HTML will be compressed by [jekyll-compress-html](https://github.com/penibelst/jekyll-compress-html) during deployment, but it cannot handle the `//` properly, which will disrupt the structure of the compressed HTML.
### External Scripts
If you need to add/change/delete the JavaScript in the directory `_javascript/`, setting up [`Node.js`](https://nodejs.org/) and [`npx`](https://www.npmjs.com/package/npx) is a requirement. And then install the development dependencies:
### Check the core functionality
```console ```console
$ npm i bash ./tools/test
``` ```
During JavaScript development, real-time debugging can be performed through the following commands: ### Check the SASS syntax style
Firstly, start a Jekyll server:
```console ```console
$ bash tools/run npm test
``` ```
And then open a new terminal tab and run: ### Verify the commits
```console Before you create a git commit, please complete the following setup.
# Type 'Ctrl + C' to stop
$ npx gulp dev
```
After debugging, run the command `npx gulp` (without any argument) will automatically output the compressed files to the directory `assets/js/dist/`.
## Verify the commit messages
If you want to make sure your commits pass the CI check, you can refer to the following steps.
Install `commitlint` & `husky`: Install `commitlint` & `husky`:
```console ```console
$ npm i -g @commitlint/{cli,config-conventional} husky npm i -g @commitlint/{cli,config-conventional} husky
``` ```
And then enable `husky`: And then enable `husky`:
```console ```console
$ husky install husky install
``` ```
--- [pr-issue]: https://github.com/cotes2020/jekyll-theme-chirpy/issues/new?labels=enhancement&template=feature_request.md
[gh-pr]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
:tada: Your volunteering will make the open-source world more beautiful, thanks again! :tada: [cc]: https://www.conventionalcommits.org/
[ci]: https://en.wikipedia.org/wiki/Continuous_integration

121
README.md
View file

@ -2,7 +2,7 @@
# Chirpy Jekyll Theme # Chirpy Jekyll Theme
A minimal, responsive, and powerful Jekyll theme for presenting professional writing. A minimal, responsive and feature-rich Jekyll theme for technical writing.
[![Gem Version](https://img.shields.io/gem/v/jekyll-theme-chirpy?color=brightgreen)](https://rubygems.org/gems/jekyll-theme-chirpy) [![Gem Version](https://img.shields.io/gem/v/jekyll-theme-chirpy?color=brightgreen)](https://rubygems.org/gems/jekyll-theme-chirpy)
[![CI](https://github.com/cotes2020/jekyll-theme-chirpy/actions/workflows/ci.yml/badge.svg)](https://github.com/cotes2020/jekyll-theme-chirpy/actions/workflows/ci.yml) [![CI](https://github.com/cotes2020/jekyll-theme-chirpy/actions/workflows/ci.yml/badge.svg)](https://github.com/cotes2020/jekyll-theme-chirpy/actions/workflows/ci.yml)
@ -10,97 +10,88 @@
[![GitHub license](https://img.shields.io/github/license/cotes2020/jekyll-theme-chirpy.svg)](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE) [![GitHub license](https://img.shields.io/github/license/cotes2020/jekyll-theme-chirpy.svg)](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE)
[![996.icu](https://img.shields.io/badge/link-996.icu-%23FF4D5B.svg)](https://996.icu) [![996.icu](https://img.shields.io/badge/link-996.icu-%23FF4D5B.svg)](https://996.icu)
[**Live Demo →**](https://cotes2020.github.io/chirpy-demo) [**Live Demo →**][demo]
[![Devices Mockup](https://chirpy-img.netlify.app/commons/devices-mockup.png)](https://cotes2020.github.io/chirpy-demo) [![Devices Mockup](https://chirpy-img.netlify.app/commons/devices-mockup.png)][demo]
</div> </div>
## Features ## Features
- Dark/Light Theme Mode <details>
- Localized UI language <summary>
- Pinned Posts <i>Click to check out the features</i>
- Hierarchical Categories </summary>
- Trending Tags <p>
- Table of Contents
- Last Modified Date of Posts
- Syntax Highlighting
- Mathematical Expressions
- Mermaid Diagram & Flowchart
- Dark/Light Mode Images
- Embed Videos
- Disqus/Utterances/Giscus Comments
- Search
- Atom Feeds
- Google Analytics
- Page Views Reporting
- SEO & Performance Optimization
## Quick Start - Dark/Light Theme Mode
- Localized UI language
- Pinned Posts
- Hierarchical Categories
- Trending Tags
- Table of Contents
- Last Modified Date of Posts
- Syntax Highlighting
- Mathematical Expressions
- Mermaid Diagram & Flowchart
- Dark/Light Mode Images
- Embed Videos
- Disqus/Utterances/Giscus Comments
- Search
- Atom Feeds
- Google Analytics
- Page Views Reporting
- SEO & Performance Optimization
Follow the instructions in the [Jekyll Docs](https://jekyllrb.com/docs/installation/) to complete the installation of the basic environment. [Git](https://git-scm.com/) also needs to be installed. </p>
</details>
### Step 1. Creating a New Site
Sign in to GitHub and browse to [**Chirpy Starter**](https://github.com/cotes2020/chirpy-starter/), click the button <kbd>Use this template</kbd> > <kbd>Create a new repository</kbd>, and name the new repository `USERNAME.github.io`, where `USERNAME` represents your GitHub username.
### Step 2. Installing Dependencies
Clone it to your local machine, go to its root directory, and run the following command to install the dependencies.
```console
$ bundle
```
### Step 3. Running Local Server
Run the following command in the root directory of your site:
```console
$ bundle exec jekyll s
```
Or run with Docker:
```console
$ docker run -it --rm \
--volume="$PWD:/srv/jekyll" \
-p 4000:4000 jekyll/jekyll \
jekyll serve
```
After a few seconds, the local service will be published at _<http://127.0.0.1:4000>_.
## Documentation ## Documentation
For more details on usage, please refer to the tutorial on the [demo website](https://cotes2020.github.io/chirpy-demo/) or [wiki](https://github.com/cotes2020/jekyll-theme-chirpy/wiki). Note that the tutorial is based on the [latest release](https://github.com/cotes2020/jekyll-theme-chirpy/releases/latest), and the features of the default branch are usually ahead of the documentation. To explore usage, development, and upgrade guide of the project, please refer to
the [Wiki][wiki].
## Contributing ## Contributing
Welcome to report bugs, improve code quality or submit a new feature. For more information, see [contributing guidelines](.github/CONTRIBUTING.md). Welcome to report bugs, help improve the code or submit new features.
For more information, please see the ["Contributing Guidelines"][contribute-guide].
## Credits ## Credits
This theme is mainly built with [Jekyll](https://jekyllrb.com/) ecosystem, [Bootstrap](https://getbootstrap.com/), [Font Awesome](https://fontawesome.com/) and some other wonderful tools (their copyright information can be found in the relevant files). The avatar and favicon design come from [Clipart Max](https://www.clipartmax.com/middle/m2i8b1m2K9Z5m2K9_ant-clipart-childrens-ant-cute/). This theme is mainly built with [Jekyll][jekyllrb] ecosystem,
[Bootstrap][bootstrap], [Font Awesome][icons] and some other [wonderful tools][lib].
The avatar and favicon design come from [Clipart Max][image].
:tada: Thanks to all the volunteers who contributed to this project, their GitHub IDs are on [this list](https://github.com/cotes2020/jekyll-theme-chirpy/graphs/contributors). Also, I won't forget those guys who submitted the issues or unmerged PR because they reported bugs, shared ideas, or inspired me to write more readable documentation. Thanks to all the [contributors][contributors]. Also, folks who submitted issues
or unmerged PRs should not be forgotten. Because they reported bugs, shared ideas,
or inspired me to write more readable documentation.
Last but not least, thank [JetBrains][jb] for providing the OSS development license. Last but not least, thanks to [JetBrains][jetbrains] for providing the
_Open Source Development_ license.
## Sponsoring ## Sponsoring
If you like it, please consider sponsoring me. It will help me to maintain this project better and I would be very grateful! If you would like to sponsor this project, the following options are available.
[![Ko-fi](https://img.shields.io/badge/-Buy%20Me%20a%20Coffee-ff5f5f?logo=ko-fi&logoColor=white)](https://ko-fi.com/coteschung) [![Ko-fi](https://img.shields.io/badge/-Buy%20Me%20a%20Coffee-ff5f5f?logo=ko-fi&logoColor=white)](https://ko-fi.com/coteschung)
[![Wechat Pay](https://img.shields.io/badge/-Tip%20Me%20on%20WeChat-brightgreen?logo=wechat&logoColor=white)][cn-donation] [![Wechat Pay](https://img.shields.io/badge/-Tip%20Me%20on%20WeChat-brightgreen?logo=wechat&logoColor=white)][donation]
[![Alipay](https://img.shields.io/badge/-Tip%20Me%20on%20Alipay-blue?logo=alipay&logoColor=white)][cn-donation] [![Alipay](https://img.shields.io/badge/-Tip%20Me%20on%20Alipay-blue?logo=alipay&logoColor=white)][donation]
## License ## License
This work is published under [MIT](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE) License. This work is published under [MIT][mit] License.
<!-- ReadMe links --> <!-- ReadMe links -->
[jb]: https://www.jetbrains.com/?from=jekyll-theme-chirpy [jekyllrb]: https://jekyllrb.com/
[cn-donation]: https://sponsor.cotes.page/ [bootstrap]: https://getbootstrap.com/
[icons]: https://fontawesome.com/
[image]: https://www.clipartmax.com/middle/m2i8b1m2K9Z5m2K9_ant-clipart-childrens-ant-cute/
[demo]: https://cotes2020.github.io/chirpy-demo/
[wiki]: https://github.com/cotes2020/jekyll-theme-chirpy/wiki
[contribute-guide]: https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/.github/CONTRIBUTING.md
[contributors]: https://github.com/cotes2020/jekyll-theme-chirpy/graphs/contributors
[lib]: https://github.com/cotes2020/chirpy-static-assets
[jetbrains]: https://www.jetbrains.com/?from=jekyll-theme-chirpy
[donation]: https://sponsor.cotes.page/
[mit]: https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/LICENSE