Extend website

[Naramsim]

This PR finalizes the skeleton for the Top10 website.

A live copy can be found at my repo: https://naramsim.github.io/Top10/

It also brings in a Github Action that builds and deploys (at every commit) the website on Github Pages.

---

@vanderaj and @mackowski, do you need a brief explanation of how everything works? Or will you understand it by looking at the files?

[Naramsim]

To test locally:

# Ensure Python 3
make install-python-requirements
make serve
# open http://localhost:8000/

[Naramsim]

I added as well a Github Action that builds and checks for dead links at every commit and on every pull request.

[mackowski]

@Naramsim looks awesome! Thank you :)
@vanderaj is a leader for this project so I will leave the final review for him.

[Naramsim]

Fixed all the conflicts again.

Are there any plans @vanderaj to get this PR merged?

[Naramsim]

@mackowski hello, sorry to ping you. I really think this PR brings in needed and useful contributions, maybe you can manage to unlock it. Or at least give me some feedback.

[mackowski]

hey @Naramsim I was on a trip without access to the internet. Yes I see that your changes are great.
I am not in charge for this project @vanderaj @infosecdad @Neil-Smithline @sslHello - what do you think about this PR?

[sslHello]

Hi Alessandro (@Naramsim),
I am sorry that we have not replied earlier.
Up to some weeks ago the upload of new gh-pages has been maintained by Andrew (@vanderaj).
As some translations were waiting to get published I've started to do it, too.

So I found your PR. Thank you very much, it looks very useful.
I'd have some questions:

• What happens if the gh-page gets broken by a pull?
• Do you think that it is possible to use it to generate the automatically generated pages as 'development' gh-page from it (how I do it locally)?
• How do you get the languages sorted in the languages menue?

Thank you and cheers
Torsten

[Naramsim]

Hi @sslHello,

1. If the build step passes, then it's impossible that the deploy step will generate and deploy a broken website. Anyway, if the GH deployment gets somehow broken, you can always revert it to a previous commit: https://github.com/OWASP/Top10/commits/gh-pages. In the end, GH is just serving static files from a specific git branch.
2. I don't understand your sentence. Can you rephrase?
3. It's a matter of ordering the dict in mkdocs.yml: https://github.com/Naramsim/Top10/blob/master/2021/mkdocs.yml#L87-L96. Note that if running mkdocs build it works as expected, while if running mkdocs serve there is an unexpected behavior and the list isn't sorted correctly. But this happens only when developing locally.

[Naramsim]

Also note that the label with name automatization, could be renamed to the more common word automation.

[Naramsim]

Update on your 2nd point. Maybe I understand what you mean.

Do you want a way to automatically generate the website, without generating it on your machine and deploying it manually? Well, this PR does exactly this. Whenever a PR will be merged in the master/main branch, a Github Action will build and deploy the website. Without any action needed by the maintainers. Please review the content on the .github folder: https://github.com/Naramsim/Top10/tree/master/.github/workflows

[Naramsim]

@sslHello, did you have time to review what I wrote?

[sslHello]

Hi @Naramsim,
thank you for your answeres. I am sorry I have been quite busy the last weeks.

• For my second question:
  Is it possible to automatically deploy the content to a different branch and to compile a development site e.g. https://owasp.github.io/Top10-Dev/ and add some banners there like 'Development version and work in progress. "For the official OWASP Top 10 site visit 'https://owasp.org/Top10/', please."
  ~ We'd like to publish new languages when they are more mature.
  ~ I am going to add 2 Mkdocs macros, that I've programmed in Python ('https://github.com/sslHello/OSIB-Test'). Do you think it works? They read and write YAML files. The new, generated file extends the YAML structure (= Open Security Information Base, OSIB). It can be used by other versions, projects, documents and standards as universal references that fix even numbering changes between versions (if linked once in the structure).
• For my third question: Yes, thanks. As far as I see, I've experienced the unexpected behavior with mkdocs serve and mkdocs gh-deploy. So the list isn't sorted correctly at https://owasp.org/Top10/.

Thank you!
Cheers Torsten

[Naramsim]

Hi!

1. it's possible but now I don't have time to implement it.
2. I wouldn't develop custom modules. But, it's up to you.

[Naramsim]

One thing that can be made to finally include this PR in the source code is disabling the CI, so you won't have any automated deployments but we will have all the other changes.

[Naramsim]

Let me know if I need to comment it out

[Naramsim]

Hi, @sslHello I came back here to see how the repo evolved. This PR can still be merged