Markdown is designed to be readable in plain-text. I think the only thing you could consider a special tag is how links are handled: [link text](url) linking to images is the same, with a prefix "!". Everything else is actually intuitive from looking at the text itself. Look here: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
Regarding using READMEs as the backend for the main NuttX documentation, as I mentioned this is not the best idea because it would indeed require adding extra tags (like links to images, etc). READMEs should be used for technical information to be read when entering a subdirectory. On the other hand, Markdown or any other more complete format (like ReStructuredText) is a very good format for maintaining documentation outside of the main nuttx repo. In this case, a doc-repo with CI could be maintained, exactly the same as the nuttx website repo (in fact, it could be the same one). The website already requires ruby (jekyll) to be built. So, in summation: - I would use Markdown (without unnecessary tags) on the READMEs - I would start a doc repo (or reuse the website repo) and create a nice looking documentation (accessible as subdirectory or subdomain of nuttx website) based on Markdown or any other useful format and some website generator like readthedocs or whatever works best. Best, Matias On Fri, Jul 17, 2020, at 11:38, Alin Jerpelea wrote: > +1 > > Plain text is the best on cmd line environments (ssh/putty) > > On Fri, Jul 17, 2020, 16:28 Gregory Nutt <spudan...@gmail.com> wrote: > > > > > > Please make sure the readmes are still easily readable in vim and > > > other plain text editors. > > > > > > Plain text is good. > > > > > > underlined plain text interpreted by github is still readable (markdown?) > > > > > > anything that requires writing explicit tag in the readme text files > > > should be avoided imho. > > > > > > > > > also, anything that requires non-trivial tools for reading is to be > > > excluded. > > > > > > asciidoctor requires ruby > > > > > > Not sure that throwing more tools in the mix is even useful... > > > > > > > > > Sebastien > > I would second that: (1) plain text with no embedded tags, and (2) no > > new tools. > > >
