Is raw markdown the best format to read?

[ChrisBeeley]

Having the whole document as one big .md doesn't give the best experience for the reader. Any scope to render with, say, Hugo, and host the HTML on GitHub pages?

[pacharanero]

I agree. The source text can and should remain in .md format, but this can easily be processed by static site generators into something that looks nicer. Hugo, Gatsby and Jekyll are all well established.

I've most recently used Material for MKDocs which is Python based and is absolutely wonderful. Another good option is Docusaurus. Both of these are aimed at technical documentation but are very amenable to creating web native 'handbooks' or other documents such as this policy.

Would agree that splitting the one big file into separate files for each of the sections might be helpful as @ChrisBeeley suggests, this makes issues more atomic, facilitates sensible git diffing and makes pull requests a bit easier to comprehend for the recipient.

[otlah]

Pushing to a static site is a great ask. I've used Jekyll before but I'll look through the options you both suggest and figure something out with our Engagement Lead.

I'm sensitive that navigating the document needs to be as easy for folks new to the platform as GitHub natives, but different structures are also definitely worth looking into!

[otlah]

Making a note for myself to look at a handful of structural changes with static site generation in issue 12.

[Lextuga007]

Given the recent developments it might be nice to consider Quarto as it works nicely between R and Python?