[Mesa-dev] [Request for Comments] - Port documentation to Markdown

[Jean Hertel]

Hello guys,


I want to propose a port of the current HTML documentation to a markdown-like syntax.


Current problems


Right now I see some problems with the approach used.

  *   People maintaining the documentation must know basic HTML syntax;
  *   There is no easy way to add a new release page;
     *   You need to open the index file and make changes there;
     *   You need to make a new file that will say what has been changed;
     *   You need to remember to update the release notes pages;
  *   The current website has many HTML tags not being closed;
  *   The website don't fit well in mobile area. (The layout is not responsive);
  *   Making any change to the layout is very hard, because you need to rewrite many pages;
  *   The current website doesn't show all the possibilities of the library. The website has a 1990 layout, and I think having a new layout would benefit the project;

Proposal for Markdown

Rewriting the documentation in a markdown syntax can bring some benefits to the development, like:

  *   Anyone writing for freedesktop.org, StackOverflow and Github already knows the markdown syntax.
  *   Independence of HTML. The developer don't need to worry if the HTML output will be correct. The generator makes all the translation from markdown to HTML;
  *   Easily change the layout of the site, simply changing the theme; (I don't think you change the layout much, but allowing it to be easy wont hurt)
  *   Creating a new release post can be maded easy, using some static site generator, for example, pelican;


Right now I have maded a partial port from HTML to Markdown.

The code can be found here: https://github.com/jlHertel/mesa-pelican

I'm using the pelican static site generator with a layout ported from Wordpress using Twitter Bootstrap CSS.

A live preview can be found here: http://mesa.jeanhertel.com.br/


The static site generator tool and the theme used can be ignored if you want, the point here is to rewrite the documentation in a way that is easy to maintain and that don't need a good knowledge in HTML.


Please leave your comments on the proposal.


Best Regards

Jean Hertel


------------------

Some terms used are web-focused, so I will leave some links if anyone don't know what I mean:

Twitter Bootstrap Css: http://getbootstrap.com/

Responsive layout: https://en.wikipedia.org/wiki/Responsive_web_design

Pelican static site generator: https://blog.getpelican.com/

Markdown: https://en.wikipedia.org/wiki/Markdown
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/mesa-dev/attachments/20170306/eb2c82f1/attachment.html>