Moving docs to a static website?

[manulera]

@ValWood @kimrutherford

This might be unnecessary, but I think it could be worth to move the docs to a markdown-based static website generator. Like this it would be easier for Val and me to add content without passing it through Kim. Especially if we are going to be adding tutorials for community curation, it's very easy to add images, embed videos etc.

Basically, these website generators create the html pages from markdown files, and the navigation / site map from the organisation of files in folders. For example, in hugo if you make a folder called about with an index.md file inside of it, this would create a button in the navigation bar about that takes you to a page that is generated from that index.md file.

I see that other MODs have their docs outside as well SGD in google sites and FlyBase in a wiki, the most obvious advantage for users vs our documentation is search. Themes for documentation in hugo or jekyll come with search as well. Below couple of examples:

https://just-the-docs.github.io/just-the-docs/ https://example.docsy.dev/docs/ https://learn.netlify.app/en/

Some also support blog posts, if we ever want to go that road.

I know this is another thing to add to the todo list if we decide to do it, but if we are planning to add substantial documentation in the coming times, it might be worth it. Also, it should be relatively easy to convert the content that is in json files right now to markdown.

[ValWood]

I don't know if this affects plans for site-wide search but I would be happy if it makes search/maintenance and editing easier.

[manulera]

The way it would typically work is that when you click on documentation it takes you to a different subdomain (docs.pombase.org) or something like that. Not sure if that would be problematic.

[kimrutherford]

Like this it would be easier for Val and me to add content without passing it through Kim.

I don't think anything needs to pass through me. All the Markdown files are here: https://github.com/pombase/website/tree/master/src/docs

Images can be added here: https://github.com/pombase/website/tree/master/src/assets

They can be edited anytime but the unfortunate down side of the current system is that changes won't be visible until the next day.

If we move to a static generator we'll need to handle the conditional sections like in this FAQ example:

https://raw.githubusercontent.com/pombase/website/master/src/docs/faq/can-i-search-pombase-for-protein-features.md

Unfortunately GitHub doesn't render it very well: https://github.com/pombase/website/blob/master/src/docs/faq/can-i-search-pombase-for-protein-features.md

Some of the pages that are in the docs directory can't be static because they have dynamic content, so they'd need special handling. Like: https://www.pombase.org/status/priority-unstudied-genes https://www.pombase.org/status/gene-characterisation

Also, it should be relatively easy to convert the content that is in json files right now to markdown.

Which content are you thinking of in JSON format?

[manulera]

Oh I see, fair enough. I thought the docs came from this kind of file:

https://github.com/pombase/website/blob/master/src/app/config/docs.json

[kimrutherford]

I thought the docs came from this kind of file

Ah, I understand now. That file is generated from the Markdown files for use in documentation search.

It's only a prototype at the moment, so it's only available on the dev site: http://dev.pombase.kmr.nz/documentation

Here is the issue where we're discussing it: https://github.com/pombase/website/issues/929

[manulera]

Aha! That searchbar looks fantastic

[kimrutherford]

I should have sent this to you earlier: https://github.com/pombase/website/wiki/Documentation-with-Markdown

[manulera]

Or I should have read the docs