Convert to mkdocs

[bentsherman]

This PR converts the docs from asciidoc to markdown / mkdocs material. This conversion is a prerequisite to merging the Nextflow docs, patterns, and Seqera training into a single docs site, which will be markdown. The PR includes the HTML build in public, so the Github pages just needs to be reconfigured to point to public directory.

To install mkdocs:

pip install mkdocs-material

To serve the website during development:

mkdocs serve

To build the static HTML:

mkdocs build

Easy!

[bentsherman]

I am following Paolo's convention here. He builds the asciidoc to html and commits it to the repository, then Github Pages hosts it. I figure we will adopt a different practice once we move forward with the website overhaul.

[ewels]

Ah ok. Mkdocs Material actually has built in functionality specifically for GitHub Actions / Pages where it builds and commits to a gh-pages branch for you but yeah like you say, no big deal especially as it's short term.

[pditommaso]

This looks nice. One thing, the mkdocs build creates the HTML into public/ instead it should be docs/ to make it work with GitHub pages.

It would be nice also to add a GH action to automate the process

[ewels]

If we're going down this route: https://squidfunk.github.io/mkdocs-material/publishing-your-site/#with-github-actions

Preference is to clean the built files out of the main development branch. The above built-in functionality builds and pushes the compiled static output to a separate branch called gh-pages which only ever contains rendered site. Then you configure the repo to build GitHub Pages from that branch.

I much prefer it as the git commit history is clean and it's clear what's editable and what's not.

[bentsherman]

I like Phil's idea. I will try to set it up.

[bentsherman]

Finally! test action is good to go. deploy action should work once you merge, and then you'll need to change the Github Pages settings to use gh-pages branch.

[pditommaso]

then you'll need to change the Github Pages settings to use gh-pages branch

How?

[bentsherman]

Go to Settings > Pages and then you will see the option under Source. You can change the branch and I also think you'll need to change the directory to root.

[ewels]

Looks like I have access to these settings too so happy to do it once we merge 👍🏻

[ewels]

https://github.com/nextflow-io/patterns/settings/pages

Branch isn't there yet, but should appear once this PR is merged and the GitHub Action runs:

[pditommaso]

Was missing this. Merging

[ewels]

Great stuff - thank you @pditommaso ! The GitHub action worked and we now have the generated site in the gh-pages branch: https://github.com/nextflow-io/patterns

The repo settings now need updating as mentioned in my comment above. I'm not sure what happened between June and now, but I no longer have admin access to this repo so can't see the settings to do it myself now sorry.

The patterns site is broken for now until this switch is pulled: http://nextflow-io.github.io/patterns/index.html

Phil

[pditommaso]

I just pressed a button 😄

[pditommaso]

he patterns site is broken for now until this switch is pulled: http://nextflow-io.github.io/patterns/index.html

What is missing for this?

[bentsherman]

Go to Settings > Pages and then you will see the option under Source. You can change the branch and I also think you'll need to change the directory to root.

[ewels]

See the screenshot in my comment above:

https://github.com/nextflow-io/patterns/settings/pages