goodcheck 2.4.4 → 2.6.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +27 -2
- data/README.md +107 -50
- data/lib/goodcheck.rb +4 -3
- data/lib/goodcheck/buffer.rb +44 -1
- data/lib/goodcheck/cli.rb +78 -54
- data/lib/goodcheck/commands/check.rb +20 -1
- data/lib/goodcheck/commands/config_loading.rb +19 -2
- data/lib/goodcheck/commands/init.rb +4 -2
- data/lib/goodcheck/commands/pattern.rb +2 -1
- data/lib/goodcheck/commands/test.rb +5 -4
- data/lib/goodcheck/config_loader.rb +6 -5
- data/lib/goodcheck/error.rb +3 -0
- data/lib/goodcheck/exit_status.rb +6 -0
- data/lib/goodcheck/glob.rb +14 -3
- data/lib/goodcheck/import_loader.rb +42 -10
- data/lib/goodcheck/version.rb +1 -1
- metadata +8 -70
- data/.gitignore +0 -13
- data/.rubocop.yml +0 -5
- data/.travis.yml +0 -11
- data/Dockerfile +0 -13
- data/Gemfile +0 -6
- data/Rakefile +0 -50
- data/bin/console +0 -14
- data/bin/setup +0 -8
- data/cheatsheet.pdf +0 -0
- data/docusaurus/.dockerignore +0 -2
- data/docusaurus/.gitignore +0 -12
- data/docusaurus/Dockerfile +0 -10
- data/docusaurus/docker-compose.yml +0 -18
- data/docusaurus/docs/commands.md +0 -69
- data/docusaurus/docs/configuration.md +0 -300
- data/docusaurus/docs/development.md +0 -15
- data/docusaurus/docs/getstarted.md +0 -46
- data/docusaurus/docs/rules.md +0 -79
- data/docusaurus/website/README.md +0 -193
- data/docusaurus/website/core/Footer.js +0 -100
- data/docusaurus/website/package.json +0 -14
- data/docusaurus/website/pages/en/index.js +0 -207
- data/docusaurus/website/pages/en/versions.js +0 -118
- data/docusaurus/website/sidebars.json +0 -11
- data/docusaurus/website/siteConfig.js +0 -171
- data/docusaurus/website/static/css/code-block-buttons.css +0 -39
- data/docusaurus/website/static/css/custom.css +0 -245
- data/docusaurus/website/static/img/favicon.ico +0 -0
- data/docusaurus/website/static/js/code-block-buttons.js +0 -47
- data/docusaurus/website/versioned_docs/version-1.0.0/commands.md +0 -70
- data/docusaurus/website/versioned_docs/version-1.0.0/configuration.md +0 -296
- data/docusaurus/website/versioned_docs/version-1.0.0/development.md +0 -16
- data/docusaurus/website/versioned_docs/version-1.0.0/getstarted.md +0 -47
- data/docusaurus/website/versioned_docs/version-1.0.0/rules.md +0 -81
- data/docusaurus/website/versioned_docs/version-1.0.2/rules.md +0 -79
- data/docusaurus/website/versioned_docs/version-2.4.0/configuration.md +0 -301
- data/docusaurus/website/versioned_docs/version-2.4.3/rules.md +0 -80
- data/docusaurus/website/versioned_sidebars/version-1.0.0-sidebars.json +0 -11
- data/docusaurus/website/versioned_sidebars/version-1.0.2-sidebars.json +0 -11
- data/docusaurus/website/versioned_sidebars/version-2.4.0-sidebars.json +0 -11
- data/docusaurus/website/versions.json +0 -8
- data/docusaurus/website/yarn.lock +0 -6844
- data/goodcheck.gemspec +0 -36
- data/goodcheck.yml +0 -10
- data/logo/GoodCheck Horizontal.pdf +0 -899
- data/logo/GoodCheck Horizontal.png +0 -0
- data/logo/GoodCheck Horizontal.svg +0 -55
- data/logo/GoodCheck logo.png +0 -0
- data/logo/GoodCheck vertical.png +0 -0
- data/sample.yml +0 -57
@@ -1,300 +0,0 @@
|
|
1
|
-
---
|
2
|
-
id: configuration
|
3
|
-
title: Configuration
|
4
|
-
sidebar_label: Configuration
|
5
|
-
---
|
6
|
-
|
7
|
-
## `goodcheck.yml`
|
8
|
-
|
9
|
-
An example of the configuration is like the following:
|
10
|
-
|
11
|
-
```yaml
|
12
|
-
rules:
|
13
|
-
- id: com.example.github
|
14
|
-
pattern: Github
|
15
|
-
message: |
|
16
|
-
GitHub is GitHub, not Github
|
17
|
-
|
18
|
-
You may misspelling the name of the service!
|
19
|
-
justification:
|
20
|
-
- When you mean a service different from GitHub
|
21
|
-
- When GitHub is renamed
|
22
|
-
glob:
|
23
|
-
- app/views/**/*.html.slim
|
24
|
-
- config/locales/**/*.yaml
|
25
|
-
pass:
|
26
|
-
- <a>Signup via GitHub</a>
|
27
|
-
fail:
|
28
|
-
- <a>Signup via Github</a>
|
29
|
-
```
|
30
|
-
|
31
|
-
The *rule* hash contains the following keys.
|
32
|
-
|
33
|
-
* `id`: a string to identify rules (required)
|
34
|
-
* `pattern`: a *pattern* or a sequence of *pattern*s
|
35
|
-
* `message`: a string to tell writers why the code piece should be revised (required)
|
36
|
-
* `justification`: a sequence of strings to tell writers when an exception can be allowed (optional)
|
37
|
-
* `glob`: a *glob* or a sequence of *glob*s (optional)
|
38
|
-
* `pass`: a string, or a sequence of strings, which does not match the given pattern (optional)
|
39
|
-
* `fail`: a string, or a sequence of strings, which does match the given pattern (optional)
|
40
|
-
|
41
|
-
## *pattern*
|
42
|
-
|
43
|
-
A *pattern* can be a *literal pattern*, *regexp pattern*, *token pattern*, or a string.
|
44
|
-
|
45
|
-
### String literal
|
46
|
-
|
47
|
-
String literal represents a *literal pattern* or *regexp pattern*.
|
48
|
-
|
49
|
-
```yaml
|
50
|
-
pattern:
|
51
|
-
- This is a literal pattern
|
52
|
-
- /This is a regexp pattern/
|
53
|
-
```
|
54
|
-
|
55
|
-
If the string value begins with `/` and ends with `/`, it is a *regexp pattern*.
|
56
|
-
You can optionally specify regexp options like `/casefold/i` or `/multiline/m`.
|
57
|
-
|
58
|
-
### *literal pattern*
|
59
|
-
|
60
|
-
*literal pattern* allows you to construct a regexp which matches exactly to the `literal` string.
|
61
|
-
|
62
|
-
```yaml
|
63
|
-
id: com.sample.GitHub
|
64
|
-
pattern:
|
65
|
-
literal: Github
|
66
|
-
case_sensitive: true
|
67
|
-
message: Write GitHub, not Github
|
68
|
-
```
|
69
|
-
|
70
|
-
All regexp meta characters included in the `literal` value will be escaped.
|
71
|
-
`case_sensitive` is an optional key and the default is `true`.
|
72
|
-
|
73
|
-
### *regexp pattern*
|
74
|
-
|
75
|
-
*regexp pattern* allows you to write a regexp with meta chars.
|
76
|
-
|
77
|
-
```yaml
|
78
|
-
id: com.sample.digits
|
79
|
-
pattern:
|
80
|
-
regexp: \d{4,}
|
81
|
-
case_sensitive: false
|
82
|
-
multiline: false
|
83
|
-
message: Insert delimiters when writing large numbers
|
84
|
-
justification:
|
85
|
-
- When you are not writing numbers, including phone numbers, zip code, ...
|
86
|
-
```
|
87
|
-
|
88
|
-
It accepts two optional attributes, `case_sensitive` and `multiline`.
|
89
|
-
The default values of `case_sensitive` and `multiline` are `true` and `false` respectively.
|
90
|
-
|
91
|
-
The regexp will be passed to `Regexp.compile`.
|
92
|
-
The precise definition of regular expressions can be found in the documentation for Ruby.
|
93
|
-
|
94
|
-
### *token pattern*
|
95
|
-
|
96
|
-
*token pattern* compiles to a *tokenized* regexp.
|
97
|
-
|
98
|
-
```yaml
|
99
|
-
id: com.sample.no-blink
|
100
|
-
pattern:
|
101
|
-
token: "<blink"
|
102
|
-
case_sensitive: false
|
103
|
-
message: Stop using <blink> tag
|
104
|
-
glob: "**/*.html"
|
105
|
-
justification:
|
106
|
-
- If Lynx is the major target of the web site
|
107
|
-
```
|
108
|
-
|
109
|
-
It tries to tokenize the input and generates a regexp which matches a sequence of tokens.
|
110
|
-
The tokenization is heuristic and may not work well for your programming language.
|
111
|
-
In that case, try using *regexp pattern*.
|
112
|
-
|
113
|
-
The generated regexp of `<blink` is `<\s*blink\b/m`.
|
114
|
-
It matches with `<blink />` and `< BLINK>`, but does not match with `https://www.chromium.org/blink`.
|
115
|
-
|
116
|
-
It accepts one optional attribute `case_sensitive`.
|
117
|
-
The default value of `case_sensitive` is `true`.
|
118
|
-
Note that the generated regexp is in multiline mode.
|
119
|
-
|
120
|
-
Token patterns can have an optional `where` attribute and *variable bindings*.
|
121
|
-
|
122
|
-
```yaml
|
123
|
-
pattern:
|
124
|
-
- token: bgcolor=${color:string}
|
125
|
-
where:
|
126
|
-
color: true
|
127
|
-
```
|
128
|
-
|
129
|
-
The variable binding consists of *variable name* and *variable type*, where `color` and `string` in the example above respectively. You have to add a key of the *variable name* in `where` attribute.
|
130
|
-
|
131
|
-
We have 8 built-in patterns:
|
132
|
-
|
133
|
-
* `string`
|
134
|
-
* `int`
|
135
|
-
* `float`
|
136
|
-
* `number`
|
137
|
-
* `url`
|
138
|
-
* `email`
|
139
|
-
* `word`
|
140
|
-
* `identifier`
|
141
|
-
|
142
|
-
You can find the exact definitions of the types in the definition of `Goodcheck::Pattern::Token` (`@@TYPES`).
|
143
|
-
|
144
|
-
You can omit the type of variable binding.
|
145
|
-
|
146
|
-
```yaml
|
147
|
-
pattern:
|
148
|
-
- token: margin-left: ${size}px;
|
149
|
-
where:
|
150
|
-
size: true
|
151
|
-
- token: backgroundColor={${color}}
|
152
|
-
where:
|
153
|
-
color: true
|
154
|
-
```
|
155
|
-
|
156
|
-
In this case, the following character will be used to detect the range of binding. In the first example above, the `px` will be used as the marker for the end of `size` binding.
|
157
|
-
|
158
|
-
If parens or brackets are surrounding the variable, Goodcheck tries to match with nested ones in the variable. It expands five levels of nesting. See the example of matches with the second `backgroundColor` pattern:
|
159
|
-
|
160
|
-
- `backgroundColor={color}` Matches (`color=="color"`)
|
161
|
-
- `backgroundColor={{ red: red(), green: green(), blue: green()-1 }}` Matches (`color=="{ red: red(), green: green(), blue: green()-1 }"`)
|
162
|
-
- `backgroundColor={ {{{{{{}}}}}} }` Matches (`color==" {{{{{{}}}}}"`)
|
163
|
-
|
164
|
-
## *glob*
|
165
|
-
|
166
|
-
A *glob* can be a string, or a hash.
|
167
|
-
|
168
|
-
```yaml
|
169
|
-
glob:
|
170
|
-
pattern: "legacy/**/*.rb"
|
171
|
-
encoding: EUC-JP
|
172
|
-
```
|
173
|
-
|
174
|
-
The hash can have an optional `encoding` attribute.
|
175
|
-
You can specify the encoding of the file by the names defined for Ruby.
|
176
|
-
The list of all available encoding names can be found by `$ ruby -e "puts Encoding.name_list"`.
|
177
|
-
The default value is `UTF-8`.
|
178
|
-
|
179
|
-
If you write a string as a `glob`, the string value can be the `pattern` of the glob, without `encoding` attribute.
|
180
|
-
|
181
|
-
If you omit the `glob` attribute in a rule, the rule will be applied to all files given to `goodcheck`.
|
182
|
-
|
183
|
-
If both your rule and its pattern has `glob`, Goodcheck will scan the pattern with files matching the `glob` condition in the pattern.
|
184
|
-
|
185
|
-
```yaml
|
186
|
-
rules:
|
187
|
-
- id: glob_test
|
188
|
-
pattern:
|
189
|
-
- literal: 123 # This pattern applies to .css files
|
190
|
-
glob: "*.css"
|
191
|
-
- literal: abc # This pattern applies to .txt files
|
192
|
-
glob: "*.txt"
|
193
|
-
```
|
194
|
-
|
195
|
-
## A rule with _negated_ pattern
|
196
|
-
|
197
|
-
Goodcheck rules are usually to detect _something is included in a file_.
|
198
|
-
You can define the _negated_ rules for the opposite, _something is missing in a file_.
|
199
|
-
|
200
|
-
```yaml
|
201
|
-
rules:
|
202
|
-
- id: negated
|
203
|
-
not:
|
204
|
-
pattern:
|
205
|
-
<!DOCTYPE html>
|
206
|
-
message: Write a doctype on HTML files.
|
207
|
-
glob: "**/*.html"
|
208
|
-
```
|
209
|
-
|
210
|
-
## A rule without `pattern`
|
211
|
-
|
212
|
-
You can define a rule without `pattern`.
|
213
|
-
The rule emits an issue on each file specified with `glob`.
|
214
|
-
You cannot omit `glob` from a rule definition without `pattern`.
|
215
|
-
|
216
|
-
```yaml
|
217
|
-
rules:
|
218
|
-
- id: without_pattern
|
219
|
-
message: |
|
220
|
-
Read the operation manual for DB migration: https://example.com/guides/123
|
221
|
-
glob: db/schema.rb
|
222
|
-
```
|
223
|
-
|
224
|
-
The output will be something like:
|
225
|
-
|
226
|
-
```
|
227
|
-
$ goodcheck check
|
228
|
-
db/schema.rb:-:# This file is auto-generated from the current state of the database. Instead: Read the operation manual for DB migration: https://example.com/guides/123
|
229
|
-
```
|
230
|
-
|
231
|
-
## Triggers
|
232
|
-
|
233
|
-
Version 2.0.0 introduces a new abstraction to define patterns, trigger.
|
234
|
-
You can continue using `pattern`s in `rule`, but using `trigger` allows more flexible pattern definition and more precise testing.
|
235
|
-
|
236
|
-
```
|
237
|
-
rules:
|
238
|
-
- id: trigger
|
239
|
-
message: Using trigger
|
240
|
-
trigger:
|
241
|
-
- pattern: <blink
|
242
|
-
glob: "**/*.html"
|
243
|
-
fail:
|
244
|
-
- <blink></blink>
|
245
|
-
- not:
|
246
|
-
pattern:
|
247
|
-
token: <meta charset="UTF-8">
|
248
|
-
case_sensitive: false
|
249
|
-
glob: "**/*.html"
|
250
|
-
pass: |
|
251
|
-
<html>
|
252
|
-
<meta charset="utf-8"></meta>
|
253
|
-
</html>
|
254
|
-
```
|
255
|
-
|
256
|
-
You can continue existing `pattern` definitions, but using `goodcheck test` against `pattern`s with `glob` does not work.
|
257
|
-
If your `pattern` definition includes `glob`, switching to `trigger` would make sense.
|
258
|
-
|
259
|
-
## Importing rules
|
260
|
-
|
261
|
-
`goodcheck.yml` can have an optional `import` attribute.
|
262
|
-
|
263
|
-
```yaml
|
264
|
-
import:
|
265
|
-
- /usr/share/goodcheck/rules.yml
|
266
|
-
- lib/goodcheck/rules.yml
|
267
|
-
- https://some.host/shared/rules.yml
|
268
|
-
```
|
269
|
-
|
270
|
-
The value of `import` can be an array of:
|
271
|
-
|
272
|
-
- A string which represents an absolute file path,
|
273
|
-
- A string which represents a relative file path from the config file, or
|
274
|
-
- A http/https URL which represents the location of rules
|
275
|
-
|
276
|
-
The rules file is a YAML file with an array of rules.
|
277
|
-
|
278
|
-
## Downloaded rules
|
279
|
-
|
280
|
-
Downloaded rules are cached in `cache` directory in *goodcheck home directory*.
|
281
|
-
The *goodcheck home directory* is `~/.goodcheck`, but you can customize the location with `GOODCHECK_HOME` environment variable.
|
282
|
-
|
283
|
-
The cache expires in 3 minutes.
|
284
|
-
|
285
|
-
## Excluding files
|
286
|
-
|
287
|
-
`goodcheck.yml` can have an optional `exclude` attribute.
|
288
|
-
|
289
|
-
```yaml
|
290
|
-
exclude:
|
291
|
-
- node_modules
|
292
|
-
- vendor
|
293
|
-
```
|
294
|
-
|
295
|
-
The value of `exclude` can be a string or an array of strings representing the glob pattern for excluded files.
|
296
|
-
|
297
|
-
|
298
|
-
## Cheatsheet
|
299
|
-
|
300
|
-
You can download a [printable cheatsheet](https://github.com/sider/goodcheck/blob/master/cheatsheet.pdf) from this repository.
|
@@ -1,15 +0,0 @@
|
|
1
|
-
---
|
2
|
-
id: development
|
3
|
-
title: Development
|
4
|
-
sidebar_label: Development
|
5
|
-
---
|
6
|
-
|
7
|
-
## Development
|
8
|
-
|
9
|
-
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
|
10
|
-
|
11
|
-
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
|
12
|
-
|
13
|
-
## Contributing
|
14
|
-
|
15
|
-
Bug reports and pull requests are welcome on [GitHub](https://github.com/sider/goodcheck).
|
@@ -1,46 +0,0 @@
|
|
1
|
-
---
|
2
|
-
id: getstarted
|
3
|
-
title: Getting Started
|
4
|
-
sidebar_label: Get Started
|
5
|
-
---
|
6
|
-
|
7
|
-
## Installation
|
8
|
-
|
9
|
-
```bash
|
10
|
-
$ gem install goodcheck
|
11
|
-
```
|
12
|
-
|
13
|
-
Or you can use `bundler`!
|
14
|
-
|
15
|
-
If you would not like to install Goodcheck to system (e.g. you would not like to install Ruby 2.4 or higher), you can use a docker image. [See below](#docker-images).
|
16
|
-
|
17
|
-
## Docker Images
|
18
|
-
|
19
|
-
We provide Docker images of Goodcheck so that you can try Goodcheck without installing them.
|
20
|
-
|
21
|
-
- https://hub.docker.com/r/sider/goodcheck/
|
22
|
-
|
23
|
-
```bash
|
24
|
-
$ docker pull sider/goodcheck
|
25
|
-
$ docker run -t --rm -v "$(pwd):/work" sider/goodcheck check
|
26
|
-
```
|
27
|
-
|
28
|
-
The default `latest` tag points to the latest release of Goodcheck.
|
29
|
-
You can pick a version of Goodcheck from [tags page](https://hub.docker.com/r/sider/goodcheck/tags).
|
30
|
-
|
31
|
-
## Quickstart
|
32
|
-
|
33
|
-
```bash
|
34
|
-
$ goodcheck init
|
35
|
-
$ vim goodcheck.yml
|
36
|
-
$ goodcheck check
|
37
|
-
```
|
38
|
-
|
39
|
-
The `init` command generates a template of `goodcheck.yml` configuration file for you.
|
40
|
-
Edit the config file to define patterns you want to check.
|
41
|
-
Then run `check` command, and it will print matched texts.
|
42
|
-
|
43
|
-
|
44
|
-
|
45
|
-
|
46
|
-
|
data/docusaurus/docs/rules.md
DELETED
@@ -1,79 +0,0 @@
|
|
1
|
-
---
|
2
|
-
id: rules
|
3
|
-
title: Rules
|
4
|
-
sidebar_label: Rules
|
5
|
-
---
|
6
|
-
|
7
|
-
|
8
|
-
## Rule: `"_blank"` Security Issue
|
9
|
-
|
10
|
-
When `target = "_blank"` is used, the opened page can access the original window object and potentially redirect the original page to a malicious URL. In this example, the rule will look for patterns of `"_blank"` and suggest to use `rel="noopener"` to prevent the opened page from having access.
|
11
|
-
|
12
|
-
```yaml
|
13
|
-
rules:
|
14
|
-
- id: security.link
|
15
|
-
pattern:
|
16
|
-
- token: 'target="_blank"'
|
17
|
-
- token: 'target: "_blank"'
|
18
|
-
message: |
|
19
|
-
Specify rel="noopener" for security reasons.
|
20
|
-
|
21
|
-
Opening new tab without rel="noopener" may cause a security issue.
|
22
|
-
It allows modifying original tab URLs from opened tabs.
|
23
|
-
justification:
|
24
|
-
- When opening a URL in our service
|
25
|
-
glob:
|
26
|
-
- "**/*.html"
|
27
|
-
- "**/*.html.erb"
|
28
|
-
fail:
|
29
|
-
- '<a href="https://github.com" target="_blank">GitHub</a>'
|
30
|
-
pass:
|
31
|
-
- '<a href="/signup">Signup</a>'
|
32
|
-
```
|
33
|
-
|
34
|
-
## Rule: Sign in
|
35
|
-
> Warning: This rule needs customization.
|
36
|
-
|
37
|
-
Keep wording consistent to provide a clear experience for users. In this example, the use of Log in or Log out would prompt the use of sign in / sign out instead.
|
38
|
-
|
39
|
-
```yaml
|
40
|
-
rules:
|
41
|
-
- id: wording.signin
|
42
|
-
pattern:
|
43
|
-
- token: Log in
|
44
|
-
case_sensitive: false
|
45
|
-
- token: Log out
|
46
|
-
case_sensitive: false
|
47
|
-
glob:
|
48
|
-
- "**/*.html.erb"
|
49
|
-
- "**/*.yml"
|
50
|
-
message: |
|
51
|
-
Please use “sign in”/“sign out”
|
52
|
-
|
53
|
-
We use “sign in” instead of “log in” and “sign out” instead of “log out”.
|
54
|
-
See the wording policy for details.
|
55
|
-
|
56
|
-
https://docs.example.com/1840
|
57
|
-
fail:
|
58
|
-
- "Log in"
|
59
|
-
- "Log out"
|
60
|
-
pass:
|
61
|
-
- "Sign in"
|
62
|
-
- "Sign out"
|
63
|
-
```
|
64
|
-
|
65
|
-
## Rule: mixin
|
66
|
-
> Warning: This rule needs customization.
|
67
|
-
|
68
|
-
A mixin lets you make groups of CSS declarations that you want to reuse throughout your site. In this example, it creates a warning when the color pattern is used and suggests using a mixin instead.
|
69
|
-
|
70
|
-
```yaml
|
71
|
-
rules:
|
72
|
-
- id: use-mixin
|
73
|
-
message: Use mixin.
|
74
|
-
pattern: "color: #038cf4;"
|
75
|
-
pass:
|
76
|
-
- "@include some-mixin;"
|
77
|
-
fail:
|
78
|
-
- "color: #038cf4;"
|
79
|
-
```
|
@@ -1,193 +0,0 @@
|
|
1
|
-
This website was created with [Docusaurus](https://docusaurus.io/).
|
2
|
-
|
3
|
-
# What's In This Document
|
4
|
-
|
5
|
-
* [Get Started in 5 Minutes](#get-started-in-5-minutes)
|
6
|
-
* [Directory Structure](#directory-structure)
|
7
|
-
* [Editing Content](#editing-content)
|
8
|
-
* [Adding Content](#adding-content)
|
9
|
-
* [Full Documentation](#full-documentation)
|
10
|
-
|
11
|
-
# Get Started in 5 Minutes
|
12
|
-
|
13
|
-
1. Make sure all the dependencies for the website are installed:
|
14
|
-
|
15
|
-
```sh
|
16
|
-
# Install dependencies
|
17
|
-
$ yarn
|
18
|
-
```
|
19
|
-
2. Run your dev server:
|
20
|
-
|
21
|
-
```sh
|
22
|
-
# Start the site
|
23
|
-
$ yarn start
|
24
|
-
```
|
25
|
-
|
26
|
-
## Directory Structure
|
27
|
-
|
28
|
-
Your project file structure should look something like this
|
29
|
-
|
30
|
-
```
|
31
|
-
my-docusaurus/
|
32
|
-
docs/
|
33
|
-
doc-1.md
|
34
|
-
doc-2.md
|
35
|
-
doc-3.md
|
36
|
-
website/
|
37
|
-
blog/
|
38
|
-
2016-3-11-oldest-post.md
|
39
|
-
2017-10-24-newest-post.md
|
40
|
-
core/
|
41
|
-
node_modules/
|
42
|
-
pages/
|
43
|
-
static/
|
44
|
-
css/
|
45
|
-
img/
|
46
|
-
package.json
|
47
|
-
sidebar.json
|
48
|
-
siteConfig.js
|
49
|
-
```
|
50
|
-
|
51
|
-
# Editing Content
|
52
|
-
|
53
|
-
## Editing an existing docs page
|
54
|
-
|
55
|
-
Edit docs by navigating to `docs/` and editing the corresponding document:
|
56
|
-
|
57
|
-
`docs/doc-to-be-edited.md`
|
58
|
-
|
59
|
-
```markdown
|
60
|
-
---
|
61
|
-
id: page-needs-edit
|
62
|
-
title: This Doc Needs To Be Edited
|
63
|
-
---
|
64
|
-
|
65
|
-
Edit me...
|
66
|
-
```
|
67
|
-
|
68
|
-
For more information about docs, click [here](https://docusaurus.io/docs/en/navigation)
|
69
|
-
|
70
|
-
## Editing an existing blog post
|
71
|
-
|
72
|
-
Edit blog posts by navigating to `website/blog` and editing the corresponding post:
|
73
|
-
|
74
|
-
`website/blog/post-to-be-edited.md`
|
75
|
-
```markdown
|
76
|
-
---
|
77
|
-
id: post-needs-edit
|
78
|
-
title: This Blog Post Needs To Be Edited
|
79
|
-
---
|
80
|
-
|
81
|
-
Edit me...
|
82
|
-
```
|
83
|
-
|
84
|
-
For more information about blog posts, click [here](https://docusaurus.io/docs/en/adding-blog)
|
85
|
-
|
86
|
-
# Adding Content
|
87
|
-
|
88
|
-
## Adding a new docs page to an existing sidebar
|
89
|
-
|
90
|
-
1. Create the doc as a new markdown file in `/docs`, example `docs/newly-created-doc.md`:
|
91
|
-
|
92
|
-
```md
|
93
|
-
---
|
94
|
-
id: newly-created-doc
|
95
|
-
title: This Doc Needs To Be Edited
|
96
|
-
---
|
97
|
-
|
98
|
-
My new content here..
|
99
|
-
```
|
100
|
-
|
101
|
-
1. Refer to that doc's ID in an existing sidebar in `website/sidebar.json`:
|
102
|
-
|
103
|
-
```javascript
|
104
|
-
// Add newly-created-doc to the Getting Started category of docs
|
105
|
-
{
|
106
|
-
"docs": {
|
107
|
-
"Getting Started": [
|
108
|
-
"quick-start",
|
109
|
-
"newly-created-doc" // new doc here
|
110
|
-
],
|
111
|
-
...
|
112
|
-
},
|
113
|
-
...
|
114
|
-
}
|
115
|
-
```
|
116
|
-
|
117
|
-
For more information about adding new docs, click [here](https://docusaurus.io/docs/en/navigation)
|
118
|
-
|
119
|
-
## Adding a new blog post
|
120
|
-
|
121
|
-
1. Make sure there is a header link to your blog in `website/siteConfig.js`:
|
122
|
-
|
123
|
-
`website/siteConfig.js`
|
124
|
-
```javascript
|
125
|
-
headerLinks: [
|
126
|
-
...
|
127
|
-
{ blog: true, label: 'Blog' },
|
128
|
-
...
|
129
|
-
]
|
130
|
-
```
|
131
|
-
|
132
|
-
2. Create the blog post with the format `YYYY-MM-DD-My-Blog-Post-Title.md` in `website/blog`:
|
133
|
-
|
134
|
-
`website/blog/2018-05-21-New-Blog-Post.md`
|
135
|
-
|
136
|
-
```markdown
|
137
|
-
---
|
138
|
-
author: Frank Li
|
139
|
-
authorURL: https://twitter.com/foobarbaz
|
140
|
-
authorFBID: 503283835
|
141
|
-
title: New Blog Post
|
142
|
-
---
|
143
|
-
|
144
|
-
Lorem Ipsum...
|
145
|
-
```
|
146
|
-
|
147
|
-
For more information about blog posts, click [here](https://docusaurus.io/docs/en/adding-blog)
|
148
|
-
|
149
|
-
## Adding items to your site's top navigation bar
|
150
|
-
|
151
|
-
1. Add links to docs, custom pages or external links by editing the headerLinks field of `website/siteConfig.js`:
|
152
|
-
|
153
|
-
`website/siteConfig.js`
|
154
|
-
```javascript
|
155
|
-
{
|
156
|
-
headerLinks: [
|
157
|
-
...
|
158
|
-
/* you can add docs */
|
159
|
-
{ doc: 'my-examples', label: 'Examples' },
|
160
|
-
/* you can add custom pages */
|
161
|
-
{ page: 'help', label: 'Help' },
|
162
|
-
/* you can add external links */
|
163
|
-
{ href: 'https://github.com/facebook/Docusaurus', label: 'GitHub' },
|
164
|
-
...
|
165
|
-
],
|
166
|
-
...
|
167
|
-
}
|
168
|
-
```
|
169
|
-
|
170
|
-
For more information about the navigation bar, click [here](https://docusaurus.io/docs/en/navigation)
|
171
|
-
|
172
|
-
## Adding custom pages
|
173
|
-
|
174
|
-
1. Docusaurus uses React components to build pages. The components are saved as .js files in `website/pages/en`:
|
175
|
-
1. If you want your page to show up in your navigation header, you will need to update `website/siteConfig.js` to add to the `headerLinks` element:
|
176
|
-
|
177
|
-
`website/siteConfig.js`
|
178
|
-
```javascript
|
179
|
-
{
|
180
|
-
headerLinks: [
|
181
|
-
...
|
182
|
-
{ page: 'my-new-custom-page', label: 'My New Custom Page' },
|
183
|
-
...
|
184
|
-
],
|
185
|
-
...
|
186
|
-
}
|
187
|
-
```
|
188
|
-
|
189
|
-
For more information about custom pages, click [here](https://docusaurus.io/docs/en/custom-pages).
|
190
|
-
|
191
|
-
# Full Documentation
|
192
|
-
|
193
|
-
Full documentation can be found on the [website](https://docusaurus.io/).
|