suggestion (non-blocking): I like the new reuse/ directory that you introduced, this builds a nice structure. We might consider renaming it to include/, which is commonly used in code. @rkratky is there any convention around this in docs?

For whatever reason, reuse is what the Starter Pack calls it, so I'm fine with it. Though include would be nicer.

note (non-blocking): Some of the includes are very small (heading + one line). But this way we're able to reuse most of it, so that's fine.

I was going to comment on this, too. There's a fine line between efficient single-sourcing and hard-decipher source files. That said, I'm fine with it as it is.

question: why did you choose to use a .txt suffix. Those are still markdown snippets after all, shouldn't they end in .md?

There was a reason for this, but I can't remember what it was :D Something to do with Sphinx, though my memory is really hazy. I'm asking around the docs group. If it turns out it's not a propblem (i.e. having .md files), I'd ask for them to be renamed to have thing intuitive (and syntax-highlighted).

Hey @rkratky & @slyon! Here's some context for the points above:

• I followed the MyST style guide which reads:

Files that only contain text that is reused somewhere else should be placed in the reuse folder and end with the extension .txt to distinguish them from normal content files.

• I created a separate prerequisites snippet for consistency because it spanned all three pages, whereas combining the prerequisite and system sections would only apply to two pages.

Let me know if you need me to make any changes.

OK, the reason for txt as opposed to md was that Sphinx then auto-excludes the TXT files (we specify only .rst and .md in the config as source files) and doesn't complain either about the file being an orphan or it starting with an out-of-order heading level. This can be prevented by adding the reuse dir in exclude_patterns in conf.py. I'd say it's better than having .txt files.