Amend Documentation (Open Source)

The documentation is built with Hugo and uses a variation of the Doks theme.

Static files for the website are built with Github actions and are published in the gh-pages branch.

How to run a local preview

1. Install Hugo. Make sure you have installed the extended version with Sass/SCSS support. Please note there are various Linux packages available on Hugo GitHub
2. Install required theme using Node.js: cd docs and then npm install.
3. To run the Docs local server, cd docs to switch to the docs folder, and start the Hugo development server by running npm run dev. Hot reloading is supported - pages will automatically update with changes while the server is running.
4. Visit http://localhost:1313.

Contribution guidelines

At this stage, our documentation is largely maintained by the DefectDojo Pro team, but we still welcome contributions to docs from the community.

• Note that our Search functionality uses an external index which points at docs.defectdojo.com - so you won’t be able to use Search to find any pages that are in dev. Instead, consult your local sitemap.xml file to find any new URLs you’ve created: http://localhost:1313/sitemap.xml
• Our docs are currently written for two audiences: Open Source and Pro, so please include an appropriate label in your Hugo front matter, like so:

  ---
  title: "Your great article"
  audience: opensource
  ---

• Do not use relative link paths: [link](../your_article/). Although technically ’legal’ in Hugo, you will not pass our unit tests.

Unit tests for docs

DefectDojo’s docs use Lychee to check for 404s and other link errors. CI runs two checks: the rendered docs site, and any docs.defectdojo.com URLs hardcoded into the Django app (templates and settings). Both use a --remap so absolute docs.defectdojo.com URLs resolve against the freshly built site. To run both locally from the root of the repo:

cd docs && rm -rf public/ && hugo --minify --gc --config config/production/hugo.toml && cd ..

lychee --offline --no-progress \
  --root-dir "$PWD/docs/public" \
  --remap "https://docs.defectdojo.com file://$PWD/docs/public" \
  './docs/public/**/*.html'

lychee --offline --no-progress \
  --root-dir "$PWD/docs/public" \
  --remap "https://docs.defectdojo.com file://$PWD/docs/public" \
  --exclude '%7[BD]' \
  $(grep -rl 'docs\.defectdojo\.com' dojo/ --include='*.html' --include='*.py' --include='*.tpl')

Theme overrides

We use significant CSS overrides which are detailed in docs/layouts.