Changed entire website to Markdown + new link checker

[atteggiani]

This is another very big PR, where the following changes have been made:

• [x] All syntax changed to Markdown (where possible) Some exceptions are cards, references (more on this below), simulated terminals, content tabs (for example the one used for different versions of ACCESS-OM2). The files related to Model Evaluation (inside docs/model_evaluation and docs/community_resources/community_med were not changed as the syntax of those files will be changed within the extensive MED restructure.

• [x] New link checker lychee (more specifically its GitHub action lychee-action) is now used for link checking. It checks for broken URLs of links and images both with Markdown and HTML syntax. In the README there is a badge that shows the status of the link checker. Ideally this should always pass. Now it is failing because there are still the MED links to check (as mentioned above).

• [x] All internal URLs changed to ABSOLUTE URLs All internal URLs (links and images) changed to absolute URLs. Internal URLs need to be ABSOLUTE URLs, starting with / which indicates the base website https://access-hive.org.au/ (http://localhost:8000/ when deploying with mkdocs serve, https://access-hive.org.au/development-website/ for the development website, and https://access-hive.org.au/pr-preview/pr-PRNUM/ for the PR previews). So, a reference to the page https://access-hive.org.au/models/configurations/access-cm/ will be /models/configurations/access-cm. Also, all assets need to be linked starting with /assets/.... This because currently the link checker does not handle relative links properly.

• [x] Custom tags To facilitate the rendering of recurring components, custom tags have been created (in the js/custom-tags.js file). Currently, the available custom tags are:

  • "NOT directly supported by ACCESS-NRI" admonition The <custom-not-supported/> tag renders a preset "NOT directly supported by ACCESS-NRI" admonition (example for community MED page).

  • References The <custom-references> ... </custom-references> tag renders references to be used at the bottom of a page. Each new line (created by pressing return/Enter) inside ... is rendered as a separate bullet point. A hyphen (-) can included at the beginning of a new line (for clarity) but it is stripped off at the time of rendering (example for How to run ACCESS-CM2 page)..

  • Simulated terminal info The <custom-simulated-terminal-info/> tag renders a preset info admonition on the pages where simulated terminal are used. It should not be used manually as it is automatically added in the pages containing simulated terminals.

• [x] README updated Updated the guidelines for developers in the README.

• [x] Other minor modifications

I understand the number of changed files is massive, but in most files content does not change much (only syntax). What I suggest for the review, apart from looking at the changes themselves, is to compare the PR-preview website to the Development website. Most pages should be exactly the same despite the changes in the syntax.

[github-actions[bot]]

PR preview :---: ⚠️ There was an error in the pr-preview deployment. For more information, please check the Actions tab. 2024-05-10 14:27 AEST

[atteggiani]

looked at the preview and layout is looking good, apart from the comment on the user support page I put in. noting with the absolute links in the cards it goes to main live site instead of the pr-preview but navigating on the left is fine to check the pages.

Yes thank you for pointing it out.

I realized it in fact I already solved it both in development (I forced push) and in this branch. Now everything works as supposed to.

There are a few caveats to that: In order to make it work, an additional javascript function needed to be implemented to change the absolute links if on the development-website or any pr-preview website. This works fine, but adds time for the page to load (not appreciable if you have an at least modest connection), even for the main website. For now I think is fine (again, it does not add much time) but, in general, many of these functions (currently embedded as a separate javascript file in js/miscellaneous.js) should take place in the build process instead, because they interact with things that cannot be altered by users. In the near future we will need to discuss the best approach to restructure the build process and customize the build so that all these changes will not influence the loading time for the pages.

@flicj191 @heidinett @KAUR1984

[atteggiani]

Thanks for the speedy and review @heidinett!

[atteggiani]

Thanks a lot @heidinett, @flicj191 and @KAUR1984 for the reviews! Merging this :)