[RFC] Markdown for documentation

There’s been some desire recently to start writing documentation in Markdown instead of reStructuredText. I put up a patch for that, but we should figure out a policy on how we want our documentation written first.

The desire to use Markdown comes mostly from it being simpler, and having much wider adoption. It does lack some of the feature that reStructuredText has; however, the recommonmark plugin for Sphinx adds extensions for most of them and has an escape to RST when all else fails.

My suggestion is that we don’t touch the existing documentation, but encourage new documentation to be written in Markdown+Sphinx extensions.

If Sphinx consumes Markdown, great, let’s do it.

We can migrate docs from .rst to .md easily over time.

Agreed. Markdown is also nice for the github integration. It might make some of our docs more easily discoverable. (and maybe editable someday)

+1, using Markdown should reduce the friction in asking people to write LLVM docs.

I’d love Markdown documentation. It’s easy to read when rendered, easy to read + navigate from a bare-bones text editor, pleasant to write, and has wide adoption. I’m a fan.

(If there are any serious missing features, we could probably look into something like Markdeep in the future, which is compatible with Markdown syntax but adds some extra functionality for documentation, writing books, etc.)

  • Jessica

It's not GitHub markdown, but it does support ``` [language]. See
AutoStructify Component — Recommonmark 0.7.1 documentation for the
extensions.

- Michael Spencer

I don’t like the fact that there are so many different Markdown versions especially when compared to RST, but it does seem that Markdown has become the more popular format. If our tooling supports it and we document what dialect we use (and perhaps even have some form of ninja check-docs to enforce it) I think that this makes sense.

– adrian

Definitely. +1 for markdown.

-Chris