Top level docs links lead to 404

[Whyborn]

The top level links in the ACCESS-ESM1.6 Documentation Overview section lead to 404s, but the sidebar links work fine. They work in the OM3 docs, and I can't tell what was done differently here.

[anton-seaice]

The link probably should be (contributing) instead of (/contributing)

[chrisb13]

H'm I think I fixed this somewhere (on other config doc rollouts) but it was because the pages was missing for the home section, and that seems to be present here:

access-esm1.6-configs/documentation/mkdocs.yml

Lines 98 to 99 in 0b7f6d3

	nav:
	- Home: pages/index.md

I can't actually re-produce the 404 that you mention @Whyborn can you be more specific?

[Whyborn]

From the landing page https://access-nri.github.io/access-esm1.6-configs/- the links to Contributing, Inputs, Configuration Choices/Configurations and Infrastructure all lead to 404

[Whyborn]

@anton-seaice that's what I thought, but the CM3 docs have the leading / and it seems to work?

[anton-seaice]

@anton-seaice that's what I thought, but the CM3 docs have the leading / and it seems to work?

Maybe this is a fluke related to the urls and intepretation of leading / as root directory ?

e.g. https://access-om3-configs.access-hive.org.au/ + /contributing. = https://access-om3-configs.access-hive.org.au/contributing/ which is correct

e.g. https://access-nri.github.io/access-esm1.6-configs/ + /contributing = https://access-nri.github.io/contributing which is bad

[chrisb13]

Any insights @atteggiani ? (Feel free to just fix if you know how)

[atteggiani]

The problem is more complex.
Mkdocs doesn't natively support absolute links.

To get around it, I created the mkdocs_resolve_absolute_urls_plugin (by modifying another one) to resolve them using the site_url field in the mkdocs.yaml.

access-esm1.6-configs/documentation/mkdocs.yml

Line 7 in 0b7f6d3

site_url: !ENV [SITE_URL, "http://access-nri.github.io/access-esm1.6-configs/"]

The SITE_URL env variable is automatically set within the deployment workflow, depending on which site is being built ("main" website or PR preview):

Main website

access-esm1.6-configs/.github/workflows/deploy_to_github_pages.yml

Lines 146 to 148 in 0b7f6d3

	dir=
	site_url="${{ env.ROOT_URL }}${dir:+${dir}/}"
	command="SITE_URL=${site_url} mkdocs build -f mkdocs.yml -d ${{env.BUILD_DIR}}"

PR preview

access-esm1.6-configs/.github/workflows/deploy_to_github_pages.yml

Lines 320 to 322 in 0b7f6d3

	dir=$(sed 's|^${{ env.ROOT_URL }}||' <<< ${{ matrix.pr_preview_url }})
	site_url="${{ env.ROOT_URL }}${dir:+${dir}/}"
	command="SITE_URL=${site_url} mkdocs build -f mkdocs.yml -d ${{env.BUILD_DIR}}"

However, the plugin is not specified in the mkdocs.yaml:

access-esm1.6-configs/documentation/mkdocs.yml

Lines 56 to 67 in 0b7f6d3

	plugins:
	- git-revision-date-localized:
	type: date
	enable_creation_date: false
	- search:
	separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
	- macros
	- bibtex:
	bib_file: references.bib
	csl_file: https://raw.githubusercontent.com/citation-style-language/styles/26eccff9e537f71494a4da7b91afac1adf571dc9/apa.csl
	- events:
	events_dir: community_resources/events/events

If I remember correctly it was removed for a reason, but that plugin is important for absolute links to work properly.
It should be added:

plugins:
   - git-revision-date-localized: 
       type: date 
       enable_creation_date: false 
   - search: 
       separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;' 
   - macros 
   - bibtex: 
       bib_file: references.bib 
       csl_file: https://raw.githubusercontent.com/citation-style-language/styles/26eccff9e537f71494a4da7b91afac1adf571dc9/apa.csl 
   - events: 
       events_dir: community_resources/events/events 
+  - resolve-absolute-urls

Note: The events plugin could instead be removed.

[chrisb13]

Thanks @atteggiani, I hope I've followed your suggestion, I've opened a PR:
#252

Feel free to review