Well the beauty of Markdown, is that it doesn't specify a lot of functionality, making it easy to understand. But when you have many, many pages of documentatio

Well the beauty of Markdown, is that it doesn't specify a lot of functionality, making it easy to understand. But when you have many, many pages of documentation, you will need to start linking them together in meaningful ways. This is where is becomes useful to have tools that can generalize things. For example, say you link to another page in your documentation repository, in Markdown, you create a link either with an absolute or relative path, specifying the filename and optionally anchor on that page. Now later down the road, you edit the folder hierarchy, or rename a page, you will now need to find all references and update them manually. Something like ReStructuredText has the "interlink" module, which allows you to modularize your pages, and use symbolic names instead of the relative or absolute path. Now, there are pros and cons to each approach, i.e. if you have a good set of tools, doing a global search and replace across documents can deal with this too. But having the flexibility of things like symbolic names and macros can make things much more manageable. Of course, this is a double edged sword, in that you can customize, create macros, until you now have a monster in of itself, but that can be said of any tool. I tend to see Markdown as perfect for standalone documents, and its especially good for formatting internet comments and the likes. Tools like DocBook and other XML processors attempt to provide the maximum amount flexibility, and the cost of a steep learning cliff and lots of boilerplate, but if implemented well, it can allow things like conditionally including parts of documentation based on tags, or output formats, but definitely requires extensive tooling as opposed to Markdown and other formats that are meant to be readable in their source form.