Testing of includes files

[paigem]

Description

This PR is to test how includes files work to ensure they do everything we want them to do. In this test, I added a file to describe persistent sessions, and then try to include it in the Run ACCESS-CM2 page.

I am trying to use includes files via the pymdownx.snippets extension, as this is something we already have in our mkdocs.yml file.

[github-actions]

PR Preview
🚀 Preview of PR head commit b82c61e deployed to https://docs.access-hive.org.au/pr-previews/1197
2026-07-07 12:32 AEST
Preview generated through the Deploy to GitHub Pages workflow run 28837342965.

[ccarouge]

@paigem @heidinett , I've started using it with the ACCESS-ESM1.5 page using the payu page I wrote as a base to include information (#1202). Here are a few thoughts:

1. I like the possibility of creating sections of files to include as snippets in other files. This way we can for example keep the payu page as a coherent page and pick and choose sections

2. Annoying thing is we can not have headers in include files. Because there is no way to modify the header level during the include and the target file might have a different layout (in terms of header levels) as the source include file.

3. We cannot have an include section that refers to another section on the same page. Because we are not sure the target page will actually include that section.

4. Include sections can refer to other pages internal or external to the documentation without the same limitation.

5. The markdown "rules" for formatting are followed. So it is possible to complete a line of text from an include file with additional text. For example, for this text:

   The laboratory directory contains all data from payu experiments of the same model. By default, it is /scratch/$PROJECT/$USER/<model_name>. $PROJECT and $USER are environment variables on Gadi that points to your default project and your username respectively. See the section on modifying the PBS resources to learn how to change the laboratory location.

   The last sentence includes a link within the page, it's possible to use a snippet for the text without the last sentence and simply add the last line after the include without leaving a blank line. So the include file could have the last sentence outside a snippet section and people writing the documentation can copy/paste it as needed. It means there would be some duplicated text but hopefully not too much. A bit clunky.

--8<-- "snippet path"
See the section on [modifying the PBS resources](https://access-hive-docs--1202.org.readthedocs.build/models/run_a_model/run_access-esm/#modify-pbs-resources) to learn how to change the laboratory location.

Items 2 and 3 make me think that include sections should be as short as possible. We should not try to have a one-to-one correspondance between a collapsible section of documentation and an include section. Include sections might be smaller, we might include several sections in a single collapsible section with potentially additional text in between to add a reference on the page.

[ccarouge]

I had a look at macros instead of snippets. The macros extension does not support including a part of a file in another file. I think that would be an annoying limitation to put the documentation together, resulting in a lot of files. I think we should encourage using Snippets but if there is a macro in the include part, then do it through Macros. In short, I don't think one tool will give us the best outcome.

I also had a look at the current includes in this test branch that have text with macros and the text can/should be changed for all of them but one occurrence. I say "should" because I think some of the text on the persistent session is wrong as it implies persistent sessions are linked to a specific model whereas we want to encourage people to use only one persistent session for everything. Persistent sessions should be linked to cylc and not a specific model. That's an aside on the testing of include files, although it makes me think macros in include files should be infrequent. Text in include files should be generic text about something (payu, rose/cylc etc.) and as such should not need to refer to specifics of the page they go in. Exceptions should be relatively rare. In turn that means recommending Snippets first and Macros for exceptions should work fine.

I'm obviously happy to discuss that point further.

[ccarouge]

I think I found a better tool!!! https://github.com/mondeja/mkdocs-include-markdown-plugin

It can do everything Snippet does, and offset Headers!!! Which means we can include headers in include sections. I like also the "rewrite-relative-urls" option so include files can use relative URLs and it will still be valid in the final file. But I believe Snippet does as well.

I think it will not work with macros inside, though. Just because of when macros are dealt with and I didn't see a way around that.