relaxing code standards for markdown

docs/markdownrules.md

@@ -16,11 +16,6 @@ language is useful for:
 Markdown language is mostly consistent across these platforms, but some
 discrepancies do exist and should be noted below.
 
-Markdown has some redundant syntax (e.g. `*italic*` and `_italic_`).
-Within CiviCRM documentation we want consistent code, so we list
-***unapproved variants*** below to make it clear which syntax is preferred by
-CiviCRM, especially in large guides like this one. 
-
 
 Basics
 ------
@@ -31,8 +26,8 @@ Basics
 -   `~~strikethrough~~` *(GitHub/Mattermost/StackExchange)*
 -   `<del>strikethrough</del>` *(mkdocs)*
 
-***Unapproved variants:*** Underscores for `_italics_` and `__bold__` work. But
-please but use asterisks for consistency.
+Alternate syntax: Underscores for `_italics_` and `__bold__` also work on most
+platforms.
 
 
 Hyperlinks
@@ -42,7 +37,7 @@ Hyperlinks
 
         Try [CiviCRM](https://civicrm.org) for your database.
 
--   With long URLs, the following syntax is better. 
+-   With long URLs, the following syntax is better.
 
         See [this issue][CRM-19799] for more details.
 
@@ -50,7 +45,7 @@ Hyperlinks
 
     -   The second line can be placed anywhere in the file.
     -   Optionally, if the link ID ("CRM-19799" in this case) is omitted, you
-        can use the link text ("this issue") to reference the link in the 
+        can use the link text ("this issue") to reference the link in the
         second line.
 
 
@@ -67,11 +62,9 @@ line.
 ```
 
 This makes it easy to avoid very long lines in markdown code. As a rule of
-thumb, **keep your markdown code free of lines longer than 80 characters**
+thumb, keep your markdown code free of lines longer than 80 characters
 where possible.
 
-Also, please **remove trailing whitespace** from the end of markdown code.
-
 **Double line breaks** create separate paragraphs:
 
 ```md
@@ -82,28 +75,27 @@ This is a second.
 ```
 
 
-
 Headings
 --------
 
-
 ```md
-Heading 1
-=========
+# Heading 1
 
-Heading 2
----------
-```
+## Heading 2
 
-***Unapproved variants:*** `# Heading 1` and `# Heading 2` also work. But please
-use `=` and `-` for consistency.
+### Heading 3
 
-For headings beyond 1 and 2, the `#` syntax is okay...
+#### Heading 4
+```
+
+Alternate syntax (only works for h1 and h2):
 
 ```md
-### Heading 3
+Heading 1
+=========
 
-#### Heading 4
+Heading 2
+---------
 ```
 
 ***Convention:*** Each page should have one and only one *Heading 1*,
@@ -111,7 +103,6 @@ which should be at the top of the page as a page title. Other headings within
 page content should be level 2 or greater.
 
 
-
 Lists
 -----
 
@@ -124,32 +115,27 @@ Lists
 -   Then, a third.
 ```
 
-***Unapproved variants:***
+Alternate syntax:
 
 -   Unordered lists also recognize `*` and `+` as item delimiters.
-    But please use `-` for consistency.
 -   Markdown is somewhat flexible with the quantity and position of spaces when
-    making lists, but for consistency, please stick to the example above which
-    has: **1 dash, 3 spaces, then content**, and has **long lines beginning
-    with 4 spaces** so they line up nicely.
+    making lists, but using 3 spaces after the dash means that sub-lists look
+    nicer in code.
 
 
 ### Ordered lists
 
 ```md
 1.  Item
-2.  Item
-3.  Item
+1.  Item
+1.  Item
 ```
 
-***Unapproved variants:*** 
+Alternate syntax:
 
 -   Ordered lists items are automatically re-numbered sequentially upon display
-    which means all items can begin with `1`, but for the sake of consistency
-    with existing docs, please number your lists sequentially in code.
--   Similar to the comment above for unordered lists, please keep all list
-    content beginning 4 characters in, which means a digit character, a period,
-    then two spaces, then content.
+    which means all items can begin with `1`, or they can be ordered
+    sequentially in code.
 
 
 ### Nested lists
@@ -201,7 +187,7 @@ BLOCK
 *Fenced code can use more backticks when necessary to represent code with
 3 backticks (which is what you'd see in the source for this page).*
 
-***Unapproved variants:*** For fenced code, the tilde `~` character also works
+Alternate syntax: For fenced code, the tilde `~` character also works
 in place of the backtick character but should be avoided for consistency.
 
 
@@ -245,15 +231,15 @@ A block of **"indented code"** with four spaces at the start of each line:
     `swift`, `tex`, `thor`, `v`, `vb`, `vbnet`, `vbs`, `vbscript`, `veo`,
     `xhtml`, `xml`, `xsl`, `yaml`, `zsh`
 -   Syntax highlighting cannot be forced for indented code.
--   Syntax highlighting is not available for inline code. 
+-   Syntax highlighting is not available for inline code.
 -   [Stack Exchange syntax highlighting][stack exchange syntax highlighting] is
     done differently.
 
 [stack exchange syntax highlighting]: http://stackoverflow.com/editing-help#syntax-highlighting
 
-### Code blocks within lists 
+### Code blocks within lists
 
-You can use **indented code within lists** by keeping a blank line 
+You can use **indented code within lists** by keeping a blank line
 above/below and indenting *4 spaces more than your list content*, like this:
 
 ```md
@@ -303,7 +289,7 @@ point and with alt text in place of the link text.
 ![Alt text](image.png)
 ```
 
-or 
+or
 
 ```md
 ![Alt text][id]
@@ -332,7 +318,7 @@ External references
 -   [Mattermost markdown](https://docs.mattermost.com/help/messaging/formatting-text.html)
 -   [Stack Exchange markdown](http://stackoverflow.com/editing-help)
 -   [GitHub markdown](https://help.github.com/categories/writing-on-github/)
--   [Official markdown reference](https://daringfireball.net/projects/markdown/syntax) 
+-   [Official markdown reference](https://daringfireball.net/projects/markdown/syntax)
     (though somewhat difficult to read)