151 lines
5.3 KiB
Markdown
151 lines
5.3 KiB
Markdown
|
# Contribution Guide
|
|||
|
|
|||
|
We always welcome everyone to contribute! Here is a guide for you.
|
|||
|
|
|||
|
## Docs
|
|||
|
|
|||
|
- [English](https://theme-hope.vuejs.press/contribution.html)
|
|||
|
- [繁體中文](https://theme-hope.vuejs.press/zh/contribution.html)
|
|||
|
- [Русский](https://theme-hope-ru.vuejs.press/contribution.html)
|
|||
|
|
|||
|
## Clone and Install Project
|
|||
|
|
|||
|
If you have not enabled corepack, run `corepack enable` first.
|
|||
|
|
|||
|
Use Git to clone the project to the local, and use `pnpm` to install dependencies.
|
|||
|
|
|||
|
```sh
|
|||
|
git clone git@github.com:vuepress-theme-hope/vuepress-theme-hope.git
|
|||
|
|
|||
|
pnpm i
|
|||
|
```
|
|||
|
|
|||
|
Note: Development requires latest LTS version of Node.js.
|
|||
|
|
|||
|
## Project File Structure
|
|||
|
|
|||
|
The project is a monorepo, managed by pnpm.
|
|||
|
|
|||
|
- `docs`: place the documentation of each plugin and theme, each subdirectory is a project
|
|||
|
- `demo`: theme demo project
|
|||
|
- `packages`: place the code of each plugin and theme, each subdirectory is a project
|
|||
|
|
|||
|
```
|
|||
|
.
|
|||
|
├── .github → GitHub config
|
|||
|
├── .husky → husky config
|
|||
|
│
|
|||
|
├── demo → Demo projects
|
|||
|
│
|
|||
|
├── docs → document directory
|
|||
|
│ ├── components → components plugin document
|
|||
|
│ ├── lightgallery → lightgallery plugin document
|
|||
|
│ ├── md-enhance → md-enhance plugin document
|
|||
|
│ ├── sass-palette → sass-palette plugin document
|
|||
|
│ ├── shared → vuepress-shared document
|
|||
|
│ ├── search-pro → search-pro plugin document
|
|||
|
│ └── theme → theme document
|
|||
|
│
|
|||
|
├── docs-shared → common files for docs
|
|||
|
|
|
|||
|
├── packages → project source code
|
|||
|
│ ├── components → components plugin
|
|||
|
│ ├── create → create-vuepress-theme-hope helper
|
|||
|
│ ├── lightgallery → lightgallery plugin
|
|||
|
│ ├── md-enhance → md-enhance plugin
|
|||
|
│ ├── sass-palette → sass-palette plugin
|
|||
|
│ ├── search-pro → search-pro plugin
|
|||
|
│ ├── shared → shared file
|
|||
|
│ └── theme → vuepress-theme-hope theme
|
|||
|
│
|
|||
|
├── scripts → command scripts
|
|||
|
│
|
|||
|
├── ... → some config files
|
|||
|
│
|
|||
|
├── LICENSE → License
|
|||
|
├── package.json → root package.json
|
|||
|
├── README.md → project intro
|
|||
|
├── SECURITY.md → Security Policy
|
|||
|
│
|
|||
|
└── tsconfig.* → TypeScript config file
|
|||
|
```
|
|||
|
|
|||
|
## Document Modification
|
|||
|
|
|||
|
You can find the corresponding project in the docs directory so you can modify the corresponding Markdown directly.
|
|||
|
|
|||
|
After ensuring that the `pnpm lint` and `pnpm lint:md` commands emit no errors, you can commit to GitHub to open a PR.
|
|||
|
|
|||
|
### Preview Docs
|
|||
|
|
|||
|
Since the docs are using local themes and plugins, you need to build the local project through `pnpm build` first.
|
|||
|
|
|||
|
To start previewing, cd to the right project under `docs` directory, then run `pnpm docs:vite-dev` (using vite) or `pnpm docs:webpack-dev` (using webpack).
|
|||
|
|
|||
|
## Project Modification
|
|||
|
|
|||
|
The structure of each project is as follows:
|
|||
|
|
|||
|
```
|
|||
|
.
|
|||
|
├── lib → compiled output file
|
|||
|
│ │
|
|||
|
│ ├── client → client-side compiled code
|
|||
|
│ │
|
|||
|
│ └── node → Node.js side compiled code
|
|||
|
│
|
|||
|
└── src → source file
|
|||
|
│
|
|||
|
├── client → client-side source code
|
|||
|
│
|
|||
|
├── node → Node.js side source code
|
|||
|
│
|
|||
|
└── shared → Shared files between node and client
|
|||
|
```
|
|||
|
|
|||
|
VuePress is running both in client side and node side. Node side has node module like `fs`, while client side is running in browser which has `document` `windows` `navigator` etc. globals, you should be aware of where a piece of code is running.
|
|||
|
|
|||
|
- `client` directory stores code running in browser
|
|||
|
- `node` directory stores code running in Node.js
|
|||
|
- `shared` directory stores files that are used in both client and node, so code shall not reference any browser globals or node module.
|
|||
|
|
|||
|
For better performance, all plugins are packed and minified using rollup when they are published.
|
|||
|
|
|||
|
## Project Development
|
|||
|
|
|||
|
1. Build project: `pnpm build`
|
|||
|
|
|||
|
- Use rollup to bundle source files and minify them, and output results to `lib` folder
|
|||
|
- Use `rollup-plugin-copy` to copy other files to `lib` folder
|
|||
|
|
|||
|
1. Develop project: `pnpm dev`
|
|||
|
|
|||
|
- Use `tsc` to compile ts file to `lib` folder
|
|||
|
- Use `cpx` to copy other files to `lib` folder
|
|||
|
|
|||
|
1. Format project: `pnpm lint`
|
|||
|
|
|||
|
It will format the project using prettier, eslint and stylelint.
|
|||
|
|
|||
|
If you modify Markdown, you also need to run the `pnpm lint:md` command.
|
|||
|
|
|||
|
Please do not mix build and dev commands as they compile in completely different ways.
|
|||
|
|
|||
|
You may need to execute the `pnpm clean` command to clear previous command result.
|
|||
|
|
|||
|
## Commit
|
|||
|
|
|||
|
The project uses `husky` to add Git Hooks for verification:
|
|||
|
|
|||
|
- In `precommit` stage: we use `lint-staged` to check the changed code with the corresponding Linter
|
|||
|
|
|||
|
This means that you need to ensure that your code is formatted by the project requirements and can pass Linter tests.
|
|||
|
|
|||
|
- In `commit-msg` stage: we use `commitlint` to verify the commit comment.
|
|||
|
|
|||
|
This means that you need to ensure that your commit comments comply with Semantic
|
|||
|
|
|||
|
If you cannot pass the above Git Hooks, you will not be able to complete `git commit`.
|
|||
|
|
|||
|
If you have already contributed something, but cannot make a commit and don’t know how to fix it, you can add the `--no-verify` flag when committing to bypass Git Hooks.
|