search

Yakifo / amqtt

Community driven LTS for HBMQTT
MIT License
131 stars 46 forks source link

Convert documentation to mkdocs-material #112

Open FlorianLudwig opened 2 years ago

FlorianLudwig commented 2 years ago

Writing markdown comes a lot easier to me (and it seems others as well) then ReStructuredText. So I suggest converting the docs to markdown and use mkdocs to generate nice looking html docs.

FlorianLudwig commented 2 years ago

@HerrMuellerluedenscheid do you have any objections?

HerrMuellerluedenscheid commented 2 years ago

I also find markdown easier to write. What I don't like about markdown is that it does not support literal includes of other files. That means that examples have to be writen inside an .md file. That means that examples cannot be integrated in CI pipelines which makes puts them at greater risk to become outdated. I mean we don't check examples right now anyway, so it wouldn't change a thing. I'm also not sure though if mkdocs has a way to allow includes of other files inside markdown. So, I'm ok with changing to markdown. Just wanted to share my thoughts :)

FlorianLudwig commented 1 year ago

Including is possible, https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#embedding-external-files

using ASCII scissors cutting a line followed by the name of the file:

--8<-- "filename.ext"