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]

@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

[vanderaj]

Narasim, Can you please resolve the conflicts, and then step me through the GitHub actions because we've been attempted to be hacked by them in the past, so I am way of the way they work. We are starting work on the 2025 version, so your changes are very welcome, but I just need to see a version that will merge successfully, and then we should meet and you can take me through the way it works.

[Naramsim]

@vanderaj I fixed the conflicts. The PR is ready to be reviewed. Please check on your machine if you can run the command mkdocs serve from the 2021/ folder. And please start with a clean Virtual Environment and install the fixed dependencies found in the 2021/ folder. You can follow the instructions.

The preview can be found at my repo's GH pages: https://naramsim.github.io/Top10/fr/

The CICD pipeline passes.

Notable changes:

• update dependencies mkdocs-material to version 9, mkdocs-static-i18n to version >1.0. This required some modifications to the structure of mkdocs.yml file. The biggest was moving the nav translations to the plugins.i18n.languages[].nav_translations section. And due to a i18n plugin restriction I had to remove the navigation.instant feature of mkdocs.
• Dropped the use of a third party GH action for publishing GH pages, and switched to the official one. This will require a repository setting change, so that the master branch will be able to publish GH pages. See the screenshot below. In red we should enable Selected branches and tags and in orange we should only allow the master branch.
• removed duplicate requirements.txt so that it's clear which one to use. The one to use is in the 2021 folder. All dependencies have been pinned. Makefile as well was moved.
• fixed a redirection bug that occurs when switching from a language back to English while on the home page: https://owasp.org/Top10/en/
• fixed search toolbar so that it shows only current-language results

---

@vanderaj, I'll send you an email at [email protected], We can schedule a call if you want so that I can explain everything I did.

[Naramsim]

@mackowski @sslHello Hi, I tried contacting @vanderaj in various (here, email, slack) ways but never ever received a reply from him. This is a very poor way of dealing with contributors willing to help you, especially considering that the Owasp foundation is based on open-source and should lead the way in terms of collaboration.

[mackowski]

@jmanico hey Jim can you help here?

[Naramsim]

Friendly ping to @vanderaj @mackowski