search

nhsx / open-source-policy

Open Source Policy development for the NHS
Other
47 stars 11 forks source link

Is raw markdown the best format to read? #5

Open ChrisBeeley opened 2 years ago

ChrisBeeley commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

Lextuga007 commented 1 year ago

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