docs(markdown-format): create adr for markdown format (#3055)

create an adr discussing how/why the team shall adopt CommonMark as the
standard for the docs-readme output target

Author: rwaskiewicz

docs/adr/0012-output-markdown-format.md

@@ -0,0 +1,61 @@
+# 12. Output Markdown Format
+
+Date: 2021.09.09
+
+## Status
+
+proposed
+
+## Context
+
+Stencil has an output target that is capable of generating markdown documentation for the components that it compiles.
+Markdown does not have a unifying standard, which has led to multiple different implementations of how the markup is
+parsed. This has resulted in various markdown renderers whose implementations yield different renderings. Depending on
+where an individual views a markdown file, the results may look incorrect. 
+
+There was a [recent pull request](https://github.com/ionic-team/stencil/pull/3042/) that the team ultimately decided to
+close for not following CommonMark, which is the proposed/intended solution. Stencil should formally decide on a 
+proposed standard and use that for guidance as to how markdown should be formatted.
+
+## Options
+
+1. [Describe the many options, their pros/cons, side effects, and any perspective a given team member has]
+2. Adopt [CommonMark](https://commonmark.org/)
+   1. Pros:
+      1. It has industry support from the likes of GitHub, GitLab, Qt, and more
+      2. It seems to be the leading effort to create an unambiguous specification for Markdown
+      3. Using a well adopted standard may lead to less chance of Markdown renderings not working as intended
+   2. Cons
+      1. Not everyone may be familiar with CommonMark, leading to confusion when reviewing pull requests
+      2. CommonMark has yet to produce a v1.0 specification
+      3. CommonMark does not define a syntax for tables, requiring they be written as
+         [HTML](https://spec.commonmark.org/0.30/#html-blocks) 
+3. Adopt [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/)
+   1. Pros:
+      1. Individuals may be more familiar with GFM, given the popularity of the platform
+      2. Using a well adopted standard may lead to less chance of Markdown renderings not working as intended
+   2. Cons:
+      1. GFM is a superset of CommonMark, which may lead to subtle incompatabilities in other renderers that do not
+         support GFM
+
+## Decision
+
+The team shall use CommonMark to guide all Markdown formatting decisions for the documentation that is generated by the
+`docs-readme` output target
+
+## Consequences
+
+- There may be changes in the CommonMark specification, which the team will need to adapt to
+  - Said changes will likely come as _other_ entities also adopt the changes, e.g. GitHub
+- Meaningful changes to certain audiences in the Stencil community (e.g. users of a specific IDE) may be turned away
+  for not following the spec
+- The team should look into tooling around style guides for CommonMark and how they may be integrated into existing
+  tests
+- There may be places where the product does not adhere to CommonMark. Cases of these divergences must be documented
+  and rectified in the output target
+
+## Links
+
+- [Closed Stencil PR - feat(markdown): improved export to markdown #3042](https://github.com/ionic-team/stencil/pull/3042/)
+- [CommonMark Homepage](https://commonmark.org/)
+- [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/)

docs/adr/README.md

@@ -11,3 +11,4 @@
 * [9. consuming-app-peer-dependencies](0009-consuming-app-peer-dependencies.md)
 * [10. deno-vendoring](0010-deno-vendoring.md)
 * [11. karma-testing-constraints](0011-karma-testing-constraints.md)
+* [12. output-markdown-format](0012-output-markdown-format.md)