Skip to content

Commit 1980c52

Browse files
MaffoochMaffooch
authored
Documentation: Guide to testing hugo pipeline locally (#12959)
* Documentation: Guide to testing hugo pipeline locally * Forgot I was on an a newer version of hugo
1 parent 0ca79ab commit 1980c52

File tree

8 files changed

+117
-44
lines changed

8 files changed

+117
-44
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@ Navigate to `http://localhost:8080` to see your new instance!
8787
* [OAuth2/SAML2](https://docs.defectdojo.com/en/open_source/archived_docs/integrations/social-authentication/)
8888
* [LDAP](https://docs.defectdojo.com/en/open_source/ldap-authentication/)
8989
* [Supported tools](https://docs.defectdojo.com/en/connecting_your_tools/parsers/)
90+
* [How to Write Documentation Locally](/docs/README.md)
9091

9192
## Supported Installation Options
9293

‎docs/README.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Guide to Writing Documentation
2+
3+
When developing documentation, there are steps to take before submitting a pull request
4+
5+
1. Writing your documentation with [hot reloading](#development-with-hot-reloading) live in your browser
6+
2. Verifying your changes with a [production build](#mimic-production-environment) to ensure Hugo will minify everything correctly
7+
8+
## Development with Hot Reloading
9+
10+
This method performs the following from the `django-DefectDojo/docs` directory:
11+
12+
1. Remove any existing packages to perform a fresh install each time: `rm -rf public node_modules`
13+
2. Install all packages: `npm install`
14+
3. Start the server: `npm run dev`
15+
4. Access the [site in the browser at http://localhost:1313](http://localhost:1313)
16+
17+
### Execution List
18+
19+
```bash
20+
rm -rf public node_modules
21+
npm install
22+
npm run dev
23+
```
24+
25+
or for a one liner:
26+
27+
```bash
28+
rm -rf public node_modules && \
29+
npm install && \
30+
npm run dev
31+
```
32+
33+
## Mimic Production Environment
34+
35+
This method performs the following from the `django-DefectDojo/docs` directory:
36+
37+
1. Remove any existing packages to perform a fresh install each time: `rm -rf public node_modules`
38+
2. Install all packages in CI mode to only install from `package-lock.json`: `npm ci`
39+
3. Run Hugo to build the site in the way the CI job does, but in development environment to point at `localhost` for integrity checks : `npm run build -- --environment development`
40+
4. Change directory to the new `public` directory to run the site locally: `cd public`
41+
5. Run a light weight webserver to server the files, and [access the site at http://localhost:8080](http://localhost:8080): `python3 -m http.server 8080`
42+
6. After killing the webserver process, navigate back to the `django-DefectDojo/docs` directory: `cd ../`
43+
44+
### Execution List
45+
46+
```bash
47+
rm -rf public node_modules
48+
npm ci
49+
npm run build -- --environment development
50+
cd public
51+
python3 -m http.server 8080
52+
cd ../
53+
```
54+
55+
or for a one liner:
56+
57+
```bash
58+
rm -rf public node_modules && \
59+
npm ci && \
60+
npm run build -- --environment development && \
61+
cd public && \
62+
python3 -m http.server 8080 && \
63+
cd ../
64+
```

‎docs/assets/scss/app.scss‎

Lines changed: 40 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,62 @@
11
// Source: https://getbootstrap.com/docs/5.3/customize/sass/#importing
22

33
// 1. Include functions first (so you can manipulate colors, SVGs, calc, etc)
4-
@import "bootstrap/scss/functions";
4+
@import "node_modules/bootstrap/scss/functions";
55

66
// 2. Include any default variable overrides here
77
@import "common/colors";
88
@import "common/variables-overrides";
99
@import "common/variables-custom";
1010

1111
// 3. Include remainder of required Bootstrap stylesheets (including any separate color mode stylesheets)
12-
@import "bootstrap/scss/variables";
13-
@import "bootstrap/scss/variables-dark";
12+
@import "node_modules/bootstrap/scss/variables";
13+
@import "node_modules/bootstrap/scss/variables-dark";
1414

1515
// 4. Include any default map overrides here
1616

1717
// 5. Include remainder of required parts
18-
@import "bootstrap/scss/maps";
19-
@import "bootstrap/scss/mixins";
20-
@import "bootstrap/scss/root";
18+
@import "node_modules/bootstrap/scss/maps";
19+
@import "node_modules/bootstrap/scss/mixins";
20+
@import "node_modules/bootstrap/scss/root";
2121

2222
// 6. Optionally include any other parts as needed
2323

2424
// Layout & components
25-
@import "bootstrap/scss/utilities";
26-
@import "bootstrap/scss/reboot";
27-
@import "bootstrap/scss/type";
28-
@import "bootstrap/scss/images";
29-
@import "bootstrap/scss/containers";
30-
@import "bootstrap/scss/grid";
31-
@import "bootstrap/scss/helpers";
32-
@import "bootstrap/scss/tables";
33-
@import "bootstrap/scss/forms";
34-
@import "bootstrap/scss/buttons";
35-
@import "bootstrap/scss/transitions";
36-
@import "bootstrap/scss/dropdown";
37-
@import "bootstrap/scss/button-group";
38-
@import "bootstrap/scss/nav";
39-
@import "bootstrap/scss/navbar";
40-
@import "bootstrap/scss/card";
41-
@import "bootstrap/scss/accordion";
42-
@import "bootstrap/scss/breadcrumb";
43-
@import "bootstrap/scss/pagination";
44-
@import "bootstrap/scss/badge";
45-
@import "bootstrap/scss/alert";
46-
@import "bootstrap/scss/progress";
47-
@import "bootstrap/scss/list-group";
48-
@import "bootstrap/scss/close";
49-
@import "bootstrap/scss/toasts";
50-
@import "bootstrap/scss/modal";
51-
@import "bootstrap/scss/tooltip";
52-
@import "bootstrap/scss/popover";
53-
@import "bootstrap/scss/carousel";
54-
@import "bootstrap/scss/spinners";
55-
@import "bootstrap/scss/offcanvas";
56-
@import "bootstrap/scss/placeholders";
25+
@import "node_modules/bootstrap/scss/utilities";
26+
@import "node_modules/bootstrap/scss/reboot";
27+
@import "node_modules/bootstrap/scss/type";
28+
@import "node_modules/bootstrap/scss/images";
29+
@import "node_modules/bootstrap/scss/containers";
30+
@import "node_modules/bootstrap/scss/grid";
31+
@import "node_modules/bootstrap/scss/helpers";
32+
@import "node_modules/bootstrap/scss/tables";
33+
@import "node_modules/bootstrap/scss/forms";
34+
@import "node_modules/bootstrap/scss/buttons";
35+
@import "node_modules/bootstrap/scss/transitions";
36+
@import "node_modules/bootstrap/scss/dropdown";
37+
@import "node_modules/bootstrap/scss/button-group";
38+
@import "node_modules/bootstrap/scss/nav";
39+
@import "node_modules/bootstrap/scss/navbar";
40+
@import "node_modules/bootstrap/scss/card";
41+
@import "node_modules/bootstrap/scss/accordion";
42+
@import "node_modules/bootstrap/scss/breadcrumb";
43+
@import "node_modules/bootstrap/scss/pagination";
44+
@import "node_modules/bootstrap/scss/badge";
45+
@import "node_modules/bootstrap/scss/alert";
46+
@import "node_modules/bootstrap/scss/progress";
47+
@import "node_modules/bootstrap/scss/list-group";
48+
@import "node_modules/bootstrap/scss/close";
49+
@import "node_modules/bootstrap/scss/toasts";
50+
@import "node_modules/bootstrap/scss/modal";
51+
@import "node_modules/bootstrap/scss/tooltip";
52+
@import "node_modules/bootstrap/scss/popover";
53+
@import "node_modules/bootstrap/scss/carousel";
54+
@import "node_modules/bootstrap/scss/spinners";
55+
@import "node_modules/bootstrap/scss/offcanvas";
56+
@import "node_modules/bootstrap/scss/placeholders";
5757

5858
// 7. Optionally include utilities API last to generate classes based on the Sass map in `_utilities.scss`
59-
@import "bootstrap/scss/utilities/api";
59+
@import "node_modules/bootstrap/scss/utilities/api";
6060

6161
// 8. Add additional custom code here
6262
@import "common/fonts";
@@ -96,4 +96,4 @@ body {
9696

9797
// 10. DocSearch
9898
@import "common/variables-docsearch";
99-
@import "@docsearch/css/dist/modal";
99+
@import "node_modules/@docsearch/css/dist/modal";

‎docs/config/development/hugo.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# Overrides for production environment
2+
baseurl = "http://localhost/"

‎docs/config/production/hugo.toml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,2 @@
11
# Overrides for production environment
2-
# baseurl = "https://documentation.defectdojo.com/"
3-
baseurl = "https://docs.defectdojo.com"
2+
baseurl = "https://docs.defectdojo.com"

‎docs/layouts/partials/head/custom-head.html‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,6 @@
11
<!-- Custom head -->
2+
{{ if site.Params.add_ons.docSearch -}}
3+
{{ $options := (dict "targetPath" "/css/main.min.css" "outputStyle" "compressed") }}
4+
{{ $style := resources.Get "scss/app.scss" | resources.ToCSS $options }}
5+
<link rel="stylesheet" href="{{ $style.Permalink }}">
6+
{{ end -}}

‎docs/package-lock.json‎

Lines changed: 2 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@
1212
"preview": "vite preview --outDir public"
1313
},
1414
"dependencies": {
15-
"@docsearch/css": "^3.9.0",
16-
"@docsearch/js": "^3.9.0",
15+
"@docsearch/css": "3.9.0",
16+
"@docsearch/js": "3.9.0",
1717
"@thulite/doks-core": "1.8.0",
1818
"@thulite/images": "3.3.0",
1919
"@thulite/inline-svg": "1.2.0",

0 commit comments

Comments
 (0)