Skip to content

Commit

Permalink
Merge pull request #679 from ACCESS-NRI/davide/link_checker
Browse files Browse the repository at this point in the history
Changed entire website to Markdown + new link checker
  • Loading branch information
atteggiani authored May 10, 2024
2 parents 47df799 + 04b470a commit 9358494
Show file tree
Hide file tree
Showing 51 changed files with 1,587 additions and 1,780 deletions.
48 changes: 18 additions & 30 deletions .github/workflows/check_links.yml
Original file line number Diff line number Diff line change
@@ -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'
39 changes: 39 additions & 0 deletions .github/workflows/lychee-config.toml
Original file line number Diff line number Diff line change
@@ -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

39 changes: 32 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/
Expand All @@ -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:
```
Expand All @@ -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)|


Expand Down
48 changes: 14 additions & 34 deletions docs/about/License.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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.
22 changes: 11 additions & 11 deletions docs/about/contact.md
Original file line number Diff line number Diff line change
@@ -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
Loading

0 comments on commit 9358494

Please sign in to comment.