You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/getting-started/running-workflow.mdx
+143
Original file line number
Diff line number
Diff line change
@@ -7,3 +7,146 @@ sidebar_position: 3
7
7
Once you have cloned your new docs repository, you will want to be able to know how to start previews, lint, build, and do all the necessary things in development.
8
8
9
9
Ideally, you would be somewhat acquainted with `npm` or `yarn` project workflows, as Docusaurus is a React-based project.
10
+
11
+
## 👨💻 Committing to your repo
12
+
13
+
As part of running `npm prepare` when initializing this repo, [**`husky`**](https://typicode.github.io/husky/#/) is installed to manage pre-commit hooks.
14
+
15
+
All commits are linted with `commitlint` with the conventional rules found in `package.json`.
16
+
17
+
`lint-staged` is used to run checks on certain _staged_ Git files when committing. The commands that are run and on what files can be found in the `package.json` under the `lint-staged` key.
18
+
19
+
:::tip
20
+
21
+
It is recommended to use the command `git commit` only after staging files.
22
+
23
+
You should generally avoid `git commit -m` or similar commands which pass in the command-line or args like `--allow-empty`.
Here is an exhaustive list of what each `npm` script does in the `package.json`.
39
+
40
+
:::caution
41
+
42
+
This is likely to change every so often and documentation may not be updated to reflect it always.
43
+
44
+
Please open an issue or PR to address it!
45
+
46
+
:::
47
+
48
+
### 🐎 `npm run start`
49
+
50
+
Run Docusaurus locally on port [http://localhost:3000](http://localhost:3000) to preview and supports automatic refresh when changes are made. This is usually used in development while making changes to Markdown or certain configuration files.
51
+
52
+
:::note
53
+
54
+
**Not all** changes made are supported by the automatic refresh and may require restarting the command.
55
+
56
+
:::
57
+
58
+
### 👷 `npm run build`
59
+
60
+
Build Docusaurus for **production** into the `./build` directory of the root folder of this project.
61
+
62
+
It is usually not necessary to do this in development and is usually only used by CI when building to be deployed.
63
+
64
+
:::caution
65
+
66
+
There is still an open issue regarding proper and stable CSS insertion ordering that may differ between `npm run start` and `npm run build` results.
67
+
68
+
Please see [**here**](https://github.com/facebook/docusaurus/issues/3678) for more details.
69
+
70
+
This is usually not an issue and can be mitigated with adding `!important` to CSS styles.
71
+
72
+
:::
73
+
74
+
### 📑 `npm run build:docs`
75
+
76
+
If you have chosen to use `docusaurus-plugin-openapi-docs` plugin for integrating OpenAPI to your docs, then this command will clean existing generated Markdown API docs and re-generate them.
77
+
78
+
This command is bundled into the `npm run build` command.
79
+
80
+
You can safely remove this script from the `package.json` if you are not using the plugin.
81
+
82
+
### 🖋️ `npm run swizzle`
83
+
84
+
[**Swizzling**](https://docusaurus.io/docs/swizzling) allows more advanced customization of React Components in Docusaurus beyond simple CSS modifications.
85
+
86
+
### ✈️ `npm run deploy`
87
+
88
+
Built-in as part of Docusaurus for [deploying](https://docusaurus.io/docs/deployment#deploying-to-github-pages) project.
89
+
90
+
:::note
91
+
92
+
This command should not be necessary to use at all.
93
+
94
+
:::
95
+
96
+
### ⌦ `npm run clear`
97
+
98
+
If you are running into some issues with error when running `npm run start`, it is recommended to use the clear command to remove all generated assets, caches or build artifacts.
99
+
100
+
### 📺 `npm run serve`
101
+
102
+
This is to be run after the `npm run build` command as it will serve the files generated by the build output from the `./build` directory for local viewing.
103
+
104
+
:::note
105
+
106
+
As `npm run build` is for production building or debugging production build issues, it should not be necessary to use `npm runs serve` except where those two scenarios require it.
107
+
108
+
:::
109
+
110
+
### 🌎 `npm run write-translations`
111
+
112
+
Only needed where [translations](https://docusaurus.io/docs/cli#docusaurus-write-translations-sitedir) are to be added.
113
+
114
+
### 🌎 `npm run write-heading-ids`
115
+
116
+
Only needed where [translations](https://docusaurus.io/docs/cli#docusaurus-write-heading-ids-sitedir) are to be added.
117
+
118
+
### ⌨️ `npm run typecheck`
119
+
120
+
Typechecking with TypeScript and `tsconfig.json`.
121
+
122
+
### ⌨️ `npm run typecheck-staged`
123
+
124
+
Typechecking _staged-only_ files which is used by `lint-staged` when committing.
125
+
126
+
### 🧼 `npm run lint`
127
+
128
+
Combined command which includes spell check, JS/TS linting, and CSS linting.
129
+
130
+
### 🧼 `npm run lint:js`
131
+
132
+
Lint JS/TS with ESLint.
133
+
134
+
### 🧼 `npm run lint:spelling`
135
+
136
+
Checking spelling with CSpell.
137
+
138
+
### 🧼 `npm run lint:style`
139
+
140
+
Lint CSS files with specific styling.
141
+
142
+
### 🧼 `npm run lint:fix`
143
+
144
+
Pass the `--fix` CLI argument to `npm run lint:js` to attempt to fix issues.
145
+
146
+
### 🖨️ `npm run format`
147
+
148
+
Run Prettier to format code before commit for consistency in the repo.
149
+
150
+
### 🥗 `npm run prepare`
151
+
152
+
After `npm install` for the very first time, `husky` is installed for Git pre-commit hooks.
0 commit comments