How to write proper documentation for Yunohost?

Contribute Room Support & doc
1

Hello,

I wanted to begin to write a page about the migration of an existing Yunohost server as I am in the process of migrating to a new physical server. (This doc could also be use to create a copy of Yunohost server for backup / sandbox for testing Yunohost upgrades or applications)

I found little guidance on how to do it efficiently. There is this page https://yunohost.org/#/write_documentation which redirect to the content of the documentation on github https://github.com/YunoHost/doc

By looking at the content of the files, there is a mix of different markdown syntax and HTML.
I know how to write Markdown but there are so many different flavors of it :neutral_face: And there is some HTML inside of it.

  1. Is there an example page to follow somewhere? As it is not plain markdown, I cannot test how it will render on my computer. (I do not really want to spend time writing something and then have to do it again.)
  2. Is there any “folders / hierarchy” to follow?

Pages I had a look at

1 Like
2

Hmmmwell basically I think it is just that :

  • by default you can write in markdown
  • for extra stuff that are not doable in markdown, you can include html code directly…

But basically I guess the first approach is to just stick with markdown. Yes, there are various flavors of markdown, but basically they all have the same common base, they usually just add extra features compared to the vanilla version. (And pretty sure we use something quite close to the vanilla version ?)

About testing rendering, I think you can just go to https://yunohost.org/#/whateveryouwant , then Echap, then copy-paste (or write) your text, then Echap again to see the rendering ?

1 Like