Changed entire website to Markdown + new link checker

.github/workflows/check_links.yml

@@ -1,38 +1,26 @@
-name: Check Markdown links
+name: Check links
 
 on: 
-  push:
-  schedule:
-    # Run at 03:07 every Sunday
-    - cron: "7 3 * * SUN"
+  pull_request: #Action fires anytime a PR is (re)opened or synchronized
+    types:
+      - opened
+      - reopened
+      - synchronize
+  schedule: 
+    # Run every Sunday at 03:07 (AEDT)
+    # AEDT is UTC+10 --> Sunday at 03:07 AEDT is Saturday at 17:07 UTC
+    - cron: "7 17 * * SAT"
   workflow_dispatch:
 
 jobs:
-  markdown-link-check:
-    if: ${{ github.event_name != 'schedule' }}
+  link-check:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@master
-    - uses: gaurav-nelson/github-action-markdown-link-check@v1
+    - name: Checkout repo
+      uses: actions/checkout@master
+
+    - name: Link checker
+      uses: lycheeverse/[email protected]
       with:
-        config-file: '.github/workflows/mlc_config.json'
-        folder-path: 'docs'
-        # Only check links in modified files to reduce false positives
-        check-modified-files-only: 'yes'
-        use-quiet-mode: 'no'
-        use-verbose-mode: 'yes'
-        base-branch: 'main'
-
-  scheduled-markdown-link-check:
-    if: ${{ github.event_name == 'schedule' }}
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@master
-    - uses: gaurav-nelson/github-action-markdown-link-check@v1
-      with:
-        use-quiet-mode: 'no'
-        use-verbose-mode: 'yes'
-        config-file: '.github/workflows/mlc_config.json'
-        folder-path: 'docs'
-        base-branch: 'main'
-
+        fail: true
+        args: --config .github/workflows/lychee-config.toml './docs/**/*.md' './docs/**/*.html'

.github/workflows/lychee-config.toml

@@ -0,0 +1,39 @@
+# Configuration file for lychee link-checker (https://github.com/lycheeverse/lychee/blob/master/lychee.example.toml)
+
+# Exclude URLs and mail addresses from checking (supports regex).
+exclude = [
+    '^https://code\.metoffice\.gov\.uk',
+    '^https://web\.archive\.org/web/',
+    '^http://127\.0\.0\.1:8000',
+    '^https://www.linkedin.com/',
+]
+
+# Exclude these filesystem paths from getting checked.
+exclude_path = [
+    "./docs/fontello",
+    "./docs/fontawesome*",
+]
+
+# Set verbose level
+verbose = "info"
+
+# Don't show interactive progress bar while checking links.
+no_progress = true
+
+# Enable link caching. This can be helpful to avoid checking the same links on
+# multiple runs.
+cache = true
+
+# Discard all cached requests older than this duration.
+max_cache_age = "3d"
+
+# Base URL or website root directory to check relative URLs.
+base = "https://access-hive.org.au/"
+
+# Check links inside `<code>` and `<pre>` blocks as well as Markdown code
+# blocks.
+include_verbatim = true
+
+# Check mail addresses
+include_mail = true
+

README.md

@@ -2,6 +2,7 @@
 [![ACCESS-Hive Badge](docs/assets/badge.svg)][website]
 [![github-contributors](https://img.shields.io/github/contributors/ACCESS-Hive/access-hive.github.io?color=blue&style=plastic)][github-repo]
 [![forum-users](https://img.shields.io/discourse/users?color=blue&label=forum&server=https%3A%2F%2Fforum.access-hive.org.au&style=plastic)][forum]
+[![link-check](https://github.com/ACCESS-NRI/access-hive.org.au/actions/workflows/link_check.yml/badge.svg)](https://github.com/ACCESS-NRI/access-hive.org.au/actions/workflows/link_check.yml)
 
 This repository is the implementation of the ACCESS-Hive website accessible at the following URL:<br>
 https://access-hive.org.au/
@@ -14,27 +15,29 @@ If you wish to add documentation to the ACCESS-Hive website check the [contribut
 ## Styling guidelines for developers
 The ACCESS-Hive website is built using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). For detailed information on markdown syntax and different features, please refer to [mkdocs-material documentation](https://squidfunk.github.io/mkdocs-material/reference/).
 
-For a detailed guide on Mk
 Please follow the guidelines below to make the Hive consistent among all the pages contributed by different people. 
 
 - Always prefer Markdown syntax to HTML when possible;
+- All internal URLs need to be ABSOLUTE links, starting with `/` which indicates the base website `https://access-hive.org.au/`. 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.
 - Titles/subtitles should NOT include: code lines/blocks, bold (titles are usually already bold), italic, links;
 - Code lines/blocks need to be used for lines/blocks of code, terminal commands and file/directory paths/names;
 - Italic needs to be used when referring to specific proper nouns (for example _Gadi_ or _payu_);
 - Bold can be used to highlight some words (please do not overuse it);
-- All types of admonitions (info, warning, etc.), collapsible and not, can be used as described in the [documentation](https://squidfunk.github.io/mkdocs-material/reference/admonitions/), but they are rendered slightly differently. For the HTML version of them, please refer to the [HTML/Markdown cheatsheet](#HTML/markdown-cheatsheet).
-- Instructions for different versions (for example different operative systems or different model versions) can be rendered using tabs (see [HTML/Markdown cheatsheet](#HTML/markdown-cheatsheet));
+- All types of admonitions (info, warning, etc.), collapsible and not, can be used as described in the [documentation](https://squidfunk.github.io/mkdocs-material/reference/admonitions/), but they are rendered slightly differently. For the HTML version of them, please refer to the [HTML/Markdown cheatsheet for the Hive](#htmlmarkdown-cheatsheet-for-the-hive).
+- Instructions for different versions (for example different operative systems or different model versions) can be rendered using tabs (see [HTML/Markdown cheatsheet for the Hive](#htmlmarkdown-cheatsheet-for-the-hive));
+- Terminal input/output examples can be rendered using [animated-terminal.js](https://github.com/atteggiani/animated-terminal.js)
 
 ### Styling Markdown using CSS
 #### Attribute lists
-To style Markdown using custom CSS, you can use [attribute lists](https://python-markdown.github.io/extensions/attr_list/#limitations) by adding the desired CSS style (in-line or adding classes as defined in the `access-nri.css` file) inside curly brackets (starting with a comma) right after the markdown syntax.
+To style Markdown using custom CSS, you can use [attribute lists](https://python-markdown.github.io/extensions/attr_list/#limitations) by adding the desired CSS style (in-line or adding classes as defined in the `access-nri.css` file) inside curly brackets (starting with a colon) right after the markdown syntax.
 
 For example, to make an image 50%-wide and with rounded borders, you can write the following:
 ```
 ![image text](/image/url/){: style="width: 50%; border-radius: 0.6rem;" }
 ```
 #### Markdown in HTML
-You can use [Markdown in HTML](https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/?h=md+in+html#markdown-in-html) by adding the `markdown` attribute inside an HTML tag.<br>You can then style the HTML tag using CSS (in-line or adding selectors to the `access-nri.css` file).
+You can use [Markdown in HTML](https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/?h=md+in+html#markdown-in-html) by adding the `markdown` attribute inside an HTML tag.<br>
+You can then style the HTML tag using CSS (in-line or adding selectors to the `access-nri.css` file).
 
 For example, to render a markdown section with half font-size, you can write the following:
 ```
@@ -46,15 +49,37 @@ For example, to render a markdown section with half font-size, you can write the
 </div>
 ```
 
+### Custom HTML tags
+Some custom HTML tags were created (in the `js/custom-tags.js` file) to facilitate the rendering of some components.<br>
+The following custom tags are available:
+
+- **"Not supported by ACCESS-NRI" admonition**<br>
+  The `<custom-not-supported/>` tag renders a preset "Not supported by ACCESS-NRI" admonition.
+
+- **References**<br>
+  The `<custom-references> ... </custom-references>` tag renders references to be used at the bottom of a page. Each new line (created by pressing <kbd>return</kbd>/<kbd>Enter</kbd>) 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.<br>
+  For example, to reference 2 links you can write:
+  ```
+  <custom-references>
+    - [First reference](first-reference-url)
+    - [Second reference](second-reference-url)
+  </custom-references>
+  ```
+
+- **Simulated terminal info**<br>
+  The `<custom-simulated-terminal-info/>` tag renders a preset info admonition on the pages where simulated terminal are used.<br>
+  It should not be used manually as it is automatically embedded in the pages containing simulated terminals.
+
+
 ### HTML/Markdown Cheatsheet for the Hive
 |Style|Markdown Syntax|HTML Syntax|Rendered example|
 |---|---|---|---|
 |**Bold**|\*\*bold**|\<b>bold\</b>|**bold**|
 |**Italic**|\_italic_|\<i>italic\</i>|_italic_|
 |**Code line**|\`code line`|\<code>code line\</code>|`code line`|
 |**Code block**|\```<br>&emsp;code block<br>```|\<pre><br>&emsp;\<code>code block\</code><br>\</pre>|<pre><code>code block</code></pre>|
-|**[Admonition](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage) (not collapsible)**|!!! warning<br>&emsp;this is a warning<br>&emsp;admonition|\<div class="admonition warning"><br>&emsp;this is a warning<br>&emsp;admonition<br>\<div>|![warning admonition](docs/assets/assets_for_readme/warning_admonition.png)|
-|**Collapsible [Admonition](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage)**|??? warning title<br>&emsp;this is a collapsible<br>&emsp;warning admonition|\<details class="warning"><br>&emsp;\<summary><br>&emsp;&emsp;\<p><br>&emsp;&emsp;&emsp;this is a collapsible<br>&emsp;&emsp;&emsp;warning admonition<br>&emsp;&emsp;\</p><br>&emsp;\</summary><br>\</details>|![collapsible warning admonition](docs/assets/assets_for_readme/collapsible_warning_admonition.gif)|
+|**[Admonition](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage) (not collapsible)**|!!! warning<br>&emsp;this is a warning admonition|\<div class="admonition warning"><br>&emsp;this is a warning<br>&emsp;admonition<br>\<div>|![warning admonition](docs/assets/assets_for_readme/warning_admonition.png)|
+|**Collapsible [Admonition](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#usage)**|??? warning title<br>&emsp;this is a collapsible warning admonition|\<details class="warning"><br>&emsp;\<summary><br>&emsp;&emsp;\<p><br>&emsp;&emsp;&emsp;this is a collapsible<br>&emsp;&emsp;&emsp;warning admonition<br>&emsp;&emsp;\</p><br>&emsp;\</summary><br>\</details>|![collapsible warning admonition](docs/assets/assets_for_readme/collapsible_warning_admonition.gif)|
 |**Tabs**|N/A|\<div class="tabLabels" label="your-tab-label"><br>&emsp;\<button>Tab1\</button><br>&emsp;\<button>Tab2\</button><br>\</div><br>\<div class="tabContents" label="your-tab-label"><br>&emsp;\<div><br>&emsp;&emsp;Content for tab1<br>&emsp;\</div><br>&emsp;\<div><br>&emsp;&emsp;Content for tab2<br>&emsp;\</div><br>\</div>|![tabs](docs/assets/assets_for_readme/tabs.gif)|
 
 

docs/about/License.md

@@ -1,3 +1,6 @@
+[cc-by-human]: https://creativecommons.org/licenses/by/4.0/
+[cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode
+
 #  License 
 
 The ACCESS-Hive is made available under the [Creative Commons Attribution
@@ -6,45 +9,22 @@ license][cc-by-human]. The following is a human-readable summary of
 license][cc-by-legal].
 
 You are free to:
-<ul>
-  <li>
-    <b>Share</b>
-    <br>
-    Copy and redistribute the material in any medium or format
-  </li>
-  <li>
-    <b>Adapt</b>
-    <br>
-    Remix, transform, and build upon the material
-  </li>
-</ul>
+
+- **Share**<br>
+  Copy and redistribute the material in any medium or format
+- **Adapt**<br>
+  Remix, transform, and build upon the material
 
 for any purpose, even commercially.
 
 The licensor cannot revoke these freedoms as long as you follow the
 license terms.
 
 Under the following terms:
-<ul>
-  <li>
-    <b>Attribution</b>
-    <br>
-    You must give appropriate credit (mentioning that your work is   derived from work that is Copyright © ACCESS-NRI and, where practical, linking to **https://www.access-nri.org.au/**), provide a [link to the license][cc-by-human], and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
-  </li>
-  <li>
-    <b>No additional restrictions</b>
-    <br>
-    You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.  With the understanding that:
-    <ul>
-      <li>
-        You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.
-      </li>
-      <li>
-        No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.
-      </li>
-    </ul>
-  </li>
-</ul>
 
-[cc-by-human]: https://creativecommons.org/licenses/by/4.0/
-[cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode
+- **Attribution**<br>
+  You must give appropriate credit (mentioning that your work is derived from work that is Copyright © ACCESS-NRI and, where practical, linking to **https://www.access-nri.org.au/**), provide a link to the [license][cc-by-human], and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
+- **No additional restrictions**<br>
+  You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits. With the understanding that:
+    - You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.
+    - No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.

docs/about/contact.md

@@ -1,25 +1,25 @@
 #  Contact 
 
-<img src = "/assets/contact-img.jpg" class="intro-img img-cover with-border" loading="lazy"/>
+![Contact](/assets/contact-img.jpg){: class="intro-img img-cover with-border" loading="lazy"}
 
-ACCESS-Hive is an initiative of the <a href="https://www.access-nri.org.au/about/what-is-access-nri/" target="_blank">Australian Earth-System Simulator (ACCESS-NRI)</a>.
+ACCESS-Hive is an initiative of the [Australian Earth-System Simulator (ACCESS-NRI)](https://www.access-nri.org.au/about/what-is-access-nri).
 
-If you encounter problems/bugs about the content of ACCESS-Hive or you want to contribute, check <a href="/about/contribute">how to contribute</a>.
+If you encounter problems/bugs about the content of ACCESS-Hive, or you want to contribute, refer to [how to contribute](/about/contribute).
 
-Check the <a href="/about/user_support">User Support page</a> if you need help, and for information on what is supported and by whom.
+Check the [User Support page](/about/user_support) if you need help, and for information on what is supported and by whom.
 
-Join the <a href="https://forum.access-hive.org.au/" target="_blank">ACCESS-Hive Community Forum</a> and find previous related discussions about the hive or the resources listed here, or start your own and make contacts with your community.
+Join the [ACCESS-Hive Community Forum](https://forum.access-hive.org.au/) and find related discussions about the resources listed here, or start your own and make contacts with your community.
 
 ## Places where you can find the ACCESS-NRI team
 
-:fontawesome-brands-discourse:{ .forum } <a href="https://forum.access-hive.org.au/" target="_blank">ACCESS-Hive Community Forum</a>
+:fontawesome-brands-discourse: [ACCESS-Hive Community Forum](https://forum.access-hive.org.au/)
 
-:fontawesome-brands-github:{ .github } <a href="https://github.com/ACCESS-NRI/" target="_blank">ACCESS-NRI Github</a>
+:fontawesome-brands-github: [ACCESS-NRI GitHub](https://github.com/ACCESS-NRI/)
 
-:fontawesome-brands-twitter:{ .twitter } <a href="https://twitter.com/ACCESS_NRI" target="_blank">ACCESS-NRI Twitter</a>
+:fontawesome-brands-twitter: [ACCESS-NRI Twitter](https://twitter.com/ACCESS_NRI)
 
-:fontawesome-brands-linkedin:{ .linkedin} <a href="https://www.linkedin.com/in/access-nri" target="_blank">ACCESS-NRI LinkedIn</a> 
+:fontawesome-brands-linkedin: [ACCESS-NRI LinkedIn](https://www.linkedin.com/in/access-nri)
 
-:fontawesome-brands-slack:{ .slack} <a href="https://access-nri.slack.com" target="_blank">ACCESS-NRI Slack channel</a>
+:fontawesome-brands-slack: [ACCESS-NRI Slack channel](https://access-nri.slack.com)
 
-[^1]: _"Contact" image source_: <a href="https://www.freepik.com/free-vector/contact-concept-landing-page_5155590.htm#page=5&query=contact%20cartoon&position=6&from_view=search&track=ais">Image by pch.vector</a> on Freepik
+[^1]: _"Contact" image source_: [Image by pch.vector](https://www.freepik.com/free-vector/contact-concept-landing-page_5155590.htm#page=5&query=contact%20cartoon&position=6&from_view=search&track=ais) on Freepik