Contribution Guide
We always welcome everyone to contribute! Here is a guide for you.
Clone and Install Project
Use Git to clone the project to the local, and use pnpm
to install dependencies.
git clone git@github.com:vuepress-theme-hope/vuepress-theme-hope.git
pnpm i
Tips
If you have not installed pnpm, please install it using the following command.
corepack enable
corepack prepare pnpm@7.2.1 --activate
Project File Structure
The project is a monorepo, managed by pnpm.
docs
: place the documentation of each plugin and theme, each subdirectory is a projectdemo
: theme demo projectpackages
: place the code of each plugin and theme, each subdirectory is a project
.
├── .github → GitHub config
├── .husky → husky config
│
├── demo → Theme demo project
│
├── docs → document directory
│ ├── blog → blog2 plugin document
│ ├── comment → comment2 plugin document
│ ├── components → components plugin document
│ ├── copy-code → copy-code2 plugin document
│ ├── feed → feed2 plugin document
│ ├── lightgallery → lightgallery plugin document
│ ├── md-enhance → md-enhance plugin document
│ ├── photo-swipe → photo-swipe document
│ ├── pwa → pwa2 plugin document
│ ├── reading-time → reading-time2 plugin document
│ ├── sass-palette → sass-palette plugin document
│ ├── seo → seo2 plugin document
│ └── theme → theme document
│
├── packages → project source code
│ ├── blog2 → blog2 plugin
│ ├── comment2 → comment2 plugin
│ ├── components → components plugin
│ ├── copy-code2 → copy-code2 plugin
│ ├── create → create-vuepress-theme-hope helper
│ ├── feed2 → feed2 plugin
│ ├── lightgallery → lightgallery plugin
│ ├── md-enhance → md-enhance plugin
│ ├── photo-swipe → photo-swipe plugin
│ ├── pwa2 → pwa2 plugin
│ ├── reading-time2 → reading-time2 plugin
│ ├── sass-palette → sass-palette plugin
│ ├── seo2 → seo2 plugin
│ ├── shared → shared file
│ ├── sitemap2 → sitemap2 plugin
│ └── 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 souce code
│
├── node → Node.js side soucecode
│
└── shared → Shared files between node and client
Since the client-side uses ES Module (import/export) and the Node.js side uses commonjs (require/exports), the code in the node and client directories cannot be cross-referenced.
client
directory stores the client code, compiled in esm formatnode
directory stores the Node.js code, compiled in cjs formatshared
directory basically stores TypeScript types, and is compiled in cjs format. It can be referenced by the client and node directories.
For better performance, all plugins are packed and minified using rollup when they are published.
Project Development
How to build
- For better performance, all plugins are packed and minified using
rollup
when they are published. - Use
cpx
package to copy and watch files in other formats from the source file to the output directory.
Command
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 tolib
folder
- Use rollup to bundle source files and minify them, and output results to
Develop project:
pnpm dev
- Use
tsc
to compile ts file tolib
folder - Use
cpx
to copy other files tolib
folder
- Use
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.
Note
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 build results.
Commit
The project uses husky
to add Git Hooks for verification:
In
precommit
stage: we uselint-staged
to check the changed code with the corresponding LinterThis 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 usecommitlint
to verify the commit comment.This means that you need to ensure that your commit comments comply with Semantic
Tips
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.