Publish documentation

[noirbizarre]

Describe the feature:

I have been working with goss a lot lately and the lack of formal documentation makes it harder to use than it should, and it makes also harder to accept goss in company project (hard to sell a project when you can't share a documentation)

Would you be open to a pull request moving the markdown documentation to MkDocs, either published on GitHub pages, either published on readthedocs.io ?

I can do it and provides:

• mkdocs scafolding
• porting the existing doc into it
• readthedoc conf or a github workflow to publish it automatically

Describe the solution you'd like The documentation being properly published somewhere with classical tooling (TOC, search, deep linking...)

Describe alternatives you've considered There are many, I suggest Mkdocs as I can quickly submit a PR to do that, but any documentation engine would be an improvement on the current situation.

[aelsabbahy]

I'm in full support of this. @petemounce has suggested mkdocs material theme in the past.

I'm open to this contribution and any feedback on how to improve the documentation.

Any suggestions on where this can be hosted?

[noirbizarre]

That's great news. I'll submit a PR for MkDocs+Material as soon as possible. For the hosting, you have 2 choices (in my opinion):

• readthedocs.io
• GitHub pages

It won't change much, except for the URL (but with goss.rocks, it can be hidden) and the way you handle documentation versioning if you want to (it's built-in on readthedocs.io, and it requires a mkdocs plugin for GitHub pages). On readthedocs, build is done by readthedocs, you can configure it using their config file, on GitHub pages, you have to craft your own workflow to publish (this is quite easy). But GitHub pages publication is under changes (GitHub heading toward full workflow instead of the special gh-pages branch deployment).

Do you already have some documentation/branding material (logo, prefered colors...) ?

[petemounce]

I've used GitHub pages with mkdocs-material; that worked fine and well. Haven't used readthedocs.

Totally supportive, happy to code review or pitch in as needed.

Are you familiar with https://diataxis.fr ?