[[working-with-markdown]]
== Working with Markdown

This section describes the aspects of working with Markdown that are particularly
relevant to Spring REST Docs.



[[working-with-markdown-limitations]]
=== Limitations

Markdown was originally designed for people writing for the web and, as such, is not as
well-suited to writing documentation as Asciidoctor. Typically, these limitations are
overcome by using another tool that builds on top of Markdown.

Markdown has no official support for tables. Spring REST Docs' default Markdown snippet
templates use https://michelf.ca/projects/php-markdown/extra/#table[Markdown Extra's table
format].



[[working-with-markdown-including-snippets]]
=== Including Snippets

Markdown has no built-in support for including one Markdown file in another. To include
the generated snippets of Markdown in your documentation, you should use an additional
tool that supports this functionality. One example that is particularly well-suited to
documenting APIs is https://github.com/tripit/slate[Slate].
