nextflow-io
Convert to mkdocs
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!
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.
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.
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
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.
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.
then you'll need to change the Github Pages settings to use gh-pages branch
How?
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.
Looks like I have access to these settings too so happy to do it once we merge 👍🏻
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:
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
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?
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.