Contribution Guide

Mr.Hope ... 2021-6-6 About 3 min

We welcome you to contribute! Here is a guide for you.

# Clone and Install project

Use Git to clone the project to the local, and use yarn to install dependencies.

git clone git@github.com:vuepress-theme-hope/vuepress-theme-hope.git

yarn

1
2
3

Tips

If you have not installed yarn, please install it using npm i -g yarn.

# Project File structure

The project is a monorepo, managed by lerna.

docs: place the documentation of each plugin and theme, each subfolder is a project
demo: theme demo project
packages: place the code of each plugin and theme, each subfolder is a project

.
├── .github → Github config
├── .husky → husky config
│
├── demo → Theme demo project
│
├── docs → document directory
│ ├── active-hash → active-hash document
│ ├── add-this → add-this document
│ ├── comment → comment document
│ ├── components → components document
│ ├── copy-code → copy-code document
│ ├── feed → feed document
│ ├── git → git document
│ ├── md-enhance → md-enhance document
│ ├── photo-swipe → photo-swipe document
│ ├── pwa → pwa document
│ ├── reading-time → reading-time document
│ ├── seo → seo document
│ ├── sitemap → sitemap document
│ └── theme → theme document
│
├── packages → project source code
│ ├── active-hash → active-hash plugin
│ ├── add-this → add-this plugin
│ ├── comment → comment plugin
│ ├── components → components plugin
│ ├── copy-code → copy-code plugin
│ ├── create → create-vuepress-theme-hope helper
│ ├── feed → feed plugin
│ ├── git → git plugin
│ ├── md-enhance → md-enhance plugin
│ ├── photo-swipe → photo-swipe plugin
│ ├── pwa → pwa plugin
│ ├── reading-time → reading-time plugin
│ ├── seo → seo plugin
│ ├── shared → shared file
│ ├── smooth-scroll → smooth-scroll plugin
│ ├── sitemap → sitemap plugin
│ ├── theme → vuepress-theme-hope theme
│ ├── theme-types → theme type definition
│ └── vuepress-typings → vuepress type definition
│
├── 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
│
└── yarn.lock → yarn version lock file

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

# Document modification

You can find the corresponding project in the docs folder so you can modify the corresponding Markdown directly.

After ensuring that the yarn run lint and yarn run lint:md commands emit no errors, you can commit to GitHub to open a PR.

To preview the project locally, since the docs are using local themes and plugins, you need to build the local project through yarn run build, and then start it with the corresponding command yarn run docs/<project abbreviation>:serve in the root directory to start devServer.

# 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
│ │
│ └── types → Type definition to be exported
│
└── src → source file
  │
  ├── client → client-side souce code
  │
  ├── node → Node.js side  soucecode
  │
  └── types → Type definition to be exported

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Since VuePress@v1 requires the client to export the plugin API through module.exports, we cannot export other types in the plugin entry file, so we point the type entrance to lib/types.

Besides, 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 folders cannot be cross-referenced.

client folder stores the client code, compiled in esm format
node folder stores the Node.js code, compiled in cjs format
types folder can only store TypeScript types. It can be referenced by the client and node folders, and finally exported as a type definition to other packages.

# Project operation and development

# How to build

Use build and watch commands provided by TypeScript to compile ts files, and output the compiled js file to the output directory.
Use cpx package to copy and watch files in other formats from the source file to the output directory.

# Command

Build project: yarn run build

It will execute the two commands yarn run build:copy and yarn run build:ts, corresponding to the two build steps.
Develop project: yarn run dev

It will execute the two commands yarn run dev:copy and yarn run dev:ts, and execute and watch the two build steps.
Format project: yarn run lint

It will execute the two commands yarn run lint:eslint and yarn run lint:prettier.

If you modify Markdown, you also need to run the yarn run lint:md command.

# Commit

The project uses husky and lint-staged to add Git Hooks for verification:

In precommit stage: 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: use commitlint to verify the commit comment.

This means that you need to ensure that your commit comments comply with Semantic