# Rustdoc: reStructuredText vs Markdown

**URL:** <https://internals.rust-lang.org/t/rustdoc-restructuredtext-vs-markdown/356>\
**Category:** tools and infrastructure\
**Created:** [August 8, 2014, 8:48pm UTC](https://internals.rust-lang.org/t/rustdoc-restructuredtext-vs-markdown/356 "2014-08-08T20:48:30Z")\
**Posts on this page:** 1\
**Showing post:** 64

<div class="post-metadata">

**Author:** ![dch](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/dch/32/1095_2.png) [@dch](https://internals.rust-lang.org/u/dch)\
**Post date:** [June 25, 2015, 8:37pm UTC](https://internals.rust-lang.org/t/rustdoc-restructuredtext-vs-markdown/356/64 "2015-06-25T20:37:24Z")

</div>

While I’m not a rust contributor I did implement Apache CouchDB’s documentation and I learned a few things that might be helpful to you.

Most important is to be clear what you’re trying to achieve. - you’ve got a book, a website, cargo - all of these have Requirements. You will need to compromise, so rank and score these. And make a timely decision.

1. What functionality is needed?

- markdown has limited advanced document functionality
- are cross-document references important?
- do you need to extend the syntax?
- do you need the same format across book, website, crates, stdlib?

1. Who is expected to write 90% of the docs? Does this tool/process make this _really_ easy for them?
2. How easy is it for occasional contributors to send in something? Over time this is equally important.
3. Do you need a native toolchain _today_ for this? I’m sure you’ll end up writing your own eventually in Rust of course!

With CouchDB, the community settled on .rst for 4 reasons IIRC:

- we have some top-level python people to fix or implement anything we needed
- the functionality was well aligned
  - the inter-doc links and HTTP/REST-style markup and plugins are a huge win for us
  - what version something was added or changed is easy
  - converting from docbook into .rst was do-able as a 1 off task. Enter pandoc, ditto for .md -\> .rst also

- the generation & publishing toolchain is very easy to install on all platforms incl Windows, Linux, BSD
- the people who were going to write the docs could live with the syntax

Note that _Sphinx_ is what we needed, which is not the same as vanilla .rst. This isn’t a big issue, but don’t confuse things.

Finally, people like me who really detest the .rst syntax just wrote the stuff in markdown and used pandoc to convert over before committing 😉 #protip.

---

_[View the full topic](https://internals.rust-lang.org/t/rustdoc-restructuredtext-vs-markdown/356)._