What is Markdown If you already familiar with Markdown, feel free to skip to the next section. is a simple documentation that implements the “core” formatting features you find in HTML. Markdown markup language It makes it very easy to create simple documentation files (the first version of this very article was created using that) them save it, put that on git, control changes, …, you got the idea. I like to think it is a “standalone” Wiki tool. You can use it inside your project without any server behind it, edit anywhere, anytime. You also don’t need any compile/build steps (differently of some project documentation generators that are being developed recently). Versions and Origins There are some slightly different versions out there. The original one was defined and published on the following link: _The overriding design goal for Markdown's formatting syntax is to make it as readable as possible. The idea is that a…_daringfireball.net Daring Fireball: Markdown You can check for syntax sample on the link below: https://daringfireball.net/projects/markdown/syntax How to get the best of it? There are several plugins, preview and syntax packages that can help you start using it on your favorite IDE/Editor. Atom Eclipse IntelliJ Visual Studio It is also rendered on all of the major coding communities: BitBucket GitHub GitLab Text only is boring, looking for more After some time using Markdown, you start trying more advanced features. Markdown has a built-in extension syntax (“code spans”): https://daringfireball.net/projects/markdown/syntax#precode With that you can embed code (of any programming language) inside your Markdown documents. This can be used for more than documentation. Specialized tools can read this code and take additional steps (such as executing the code, and rendering the output of it). Just as one example, the following tool, runs “R” blocks and generate result reports: _Turn your analyses into high quality documents, reports, presentations and dashboards with R Markdown. Use a productive…_rmarkdown.rstudio.com R Markdown Examples: http://rmarkdown.rstudio.com/gallery.html This type of tool/technique is usually call "notebook". Similar tools: Apache Zeppelin ( ) https://zeppelin.apache.org/docs/0.7.0/interpreter/markdown.html ) Jupyter (http://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Working%20With%20Markdown%20Cells.html What about diagrams? Wouldn’t it be great to have a simple language that can be used to create technical diagrams, without the need to drag and drop boxes around or worry about too many details? does exactly that. PlantUML It defines a markup (human readable language) for diagraming that implement the very basics of other technical diagraming tools. Main links for that: PlantUML Home page — with links to example and specification Tools that provide PlantUML support Sample Diagrams Example 1: Sample sequence diagram Example 2: Sample component diagram How to make them work together On the Open Source world, the best option is probably to integrate PlantUML on your Markdown using images generated by Gravizo. See can see a demo here: _plantuml_with_gravizo - PlantUML with Gravizo Samples_github.com htssouza/plantuml_with_gravizo On Enterprise projects, you can use PlantUML directly on Confluence: _Macros to add various UML diagrams and other diagrams_marketplace.atlassian.com PlantUML for Confluence You can also setup the integration on your Git Lab server: https://docs.gitlab.com/ee/administration/integration/plantuml.html I hope this article helps you to get more from Markdown on your next project!
