OS Docs Overhaul - theming change, many new articles

[paulOsinski]

This PR changes the base theme from Docsy into the more workable 'Doks' theme. (It has a dark mode - sold). It also adds many new tutorials and guides to our docs.

Hugo is still a dependency. However with this version of the repo there is no need to install the theme as a git submodule. Instead, cd into docs, npm install to pull the theme and then npm run dev to view the docs locally with the new theme in place.

• Instructions on configuring, installing and maintaining an open source repo are now stored under "Open Source DefectDojo".
• Certain OS Docs have been moved to an archive due to redundancy.
• The new docs are focused on describing features, and guides on using a working instance.

[dryrunsecurity]

DryRun Security Summary

The changes in this pull request focus on updating the project's .gitignore file and the GitHub Actions workflow responsible for building and deploying the website to GitHub Pages, which do not directly impact the application's security but require review to ensure no sensitive information is committed and that the new versions of the tools being used (Hugo and Node.js) do not introduce any security vulnerabilities.

Expand for full summary

Summary:

The changes in this pull request are primarily focused on updating the project's .gitignore file and the GitHub Actions workflow responsible for building and deploying the website to GitHub Pages. From an application security perspective, these changes do not directly impact the application's security, but it's important to review them to ensure that no sensitive information is being inadvertently committed to the repository and that the new versions of the tools being used (Hugo and Node.js) do not introduce any security vulnerabilities.

The .gitignore file updates are related to managing the project's documentation-related files and configurations, which is a common practice to keep sensitive information out of the version control system. The GitHub Actions workflow updates include upgrading the Hugo and Node.js versions, caching dependencies, and simplifying the workflow. While these changes are generally positive, it's crucial to ensure that the new versions of the tools do not introduce any security issues and that the Hugo configuration file and GitHub Pages deployment settings are properly secured.

Files Changed:

1. .gitignore: The changes to the .gitignore file are focused on excluding various documentation-related files and configurations from the Git repository, such as generated files, development environment configurations, and license information. These changes do not directly impact the application's security, but it's important to ensure that no sensitive information is being inadvertently committed to the repository.

2. .github/workflows/gh-pages.yml: The changes to the GitHub Actions workflow include upgrading the Hugo and Node.js versions, caching dependencies, and simplifying the workflow. These changes are generally positive, but it's important to ensure that the new versions of the tools do not introduce any security vulnerabilities and that the Hugo configuration file and GitHub Pages deployment settings are properly secured.

Code Analysis

We ran 9 analyzers against 30 files and 0 analyzers had findings. 9 analyzers had no findings.

Riskiness

🟢 Risk threshold not exceeded.

View PR in the DryRun Dashboard.

[github-actions]

This pull request has conflicts, please resolve those before we can evaluate the pull request.

[kiblik]

Is it possible to increase the versions of Hugo and Node?

django-DefectDojo/.github/workflows/gh-pages.yml

Lines 17 to 26 in 090b2c7

	- name: Setup Hugo
	uses: peaceiris/actions-hugo@v3
	with:
	hugo-version: '0.81.0'
	extended: true
	- name: Setup Node
	uses: actions/setup-node@v4
	with:
	node-version: '20.x'

[github-actions]

Conflicts have been resolved. A maintainer will review the pull request shortly.

[kiblik]

Is it possible to increase the versions of Hugo and Node?

django-DefectDojo/.github/workflows/gh-pages.yml

Lines 17 to 26 in 090b2c7

	- name: Setup Hugo
	uses: peaceiris/actions-hugo@v3
	with:
	hugo-version: '0.81.0'
	extended: true
	- name: Setup Node
	uses: actions/setup-node@v4
	with:
	node-version: '20.x'

Note for maintainers: This will need to be adjusted as well https://github.com/DefectDojo-Inc/Documentation/blob/c6e1a446c3dbf2c931972cfbbdaef3ee20df77c8/.github/workflows/deploy-gh-pages-branch.yml#L11-L20

[mtesauro]

I agree with @kiblik about making sure we rev the versions as part of this upgrade to the docs site.

Can't wait for docs dark mode 😄

[paulOsinski]

@kiblik yes, that change was done in this commit.

[Maffooch]

Tests will need to be updated to point at the new doc paths:

• django-DefectDojo/unittests/test_parsers.py

  Line 31 in 8b20fa0

  doc_file = os.path.join(basedir, "docs", "content", "en", "integrations", "parsers", category, f"{doc_name}.md")

• django-DefectDojo/unittests/test_parsers.py

  Line 106 in 8b20fa0

  for docs in os.scandir(os.path.join(basedir, "docs", "content", "en", "integrations", "parsers", "file")):

[paulOsinski]

Tests will need to be updated to point at the new doc paths:

• django-DefectDojo/unittests/test_parsers.py

  Line 31 in 8b20fa0

  doc_file = os.path.join(basedir, "docs", "content", "en", "integrations", "parsers", category, f"{doc_name}.md")

• django-DefectDojo/unittests/test_parsers.py

  Line 106 in 8b20fa0

  for docs in os.scandir(os.path.join(basedir, "docs", "content", "en", "integrations", "parsers", "file")):

This should be settled now, thanks!

[Maffooch]

There will likely be some revving on this to make sure the automation is set correctly here

Will have to do that once it is in dev

[mtesauro]

Approved