...
` element.
+## Replace `THIS WILL NOT WORK!
<=== this will not work
+✔️ ...
` element, as in:
-
-```
-
- # This will work
-
-```
-
-While some browsers will still recognize the HTML construct `...`, it is possible **they MIGHT NOT** in the future.
-
-Jump to: [top](#)
-
-
-## If you can, it is PREFERABLE to use markdown links rather than `...`
-
-
-It is easier and preferred to use markdown links rather than HTML `..`
-anchors.
-
-Instead of:
-
-
-```
- Use of
+## Replace ``
-```
- [markdown links](#links) are easier and preferred
+```
+❌ old tags
+✔️ HTML 5 tags
```
-Jump to: [top](#)
+
-
-
+## Replace ``
-Please do **NOT** use the obsolete `
-## Please do NOT use the `` or the `` HTML element
-
-
-
-
-Please do **NOT** use the obsolete `` (_underline_) HTML element:
-
-```
- ... <=== no thank you
+```
+❌ obsolete HTML
+✔️ monospace font
+✔️ `markdown style monospace`
```
-Use instead:
+
-```
- ...
-```
-
-Jump to: [top](#)
-
-
-## Please do NOT use the `` HTML element
-
-
-
+## Indent code blocks by four spaces, not by TAB.
-Please do **NOT** use the obsolete ``
-(**teletype**) HTML element:
-
-```
- The tt element is obsolete <=== no thank you
+```
+❌ echo "This code block is NOT indented"
```
-Instead use either a monospaced `` or an inline markdown code block:
-
-```
- Use of a monospaced font
- is one option,
- however ...
-```
-
-We recommend using the inline markdown code block method instead:
-
-```
- Using the `inline markdown code block` is easier and is **preferred**.
-```
+We request that you indent the code block by multiples of four (4)
+ASCII SPACES, never TAB (␉):
-Jump to: [top](#)
+````
+✔️ echo "This code block is indented by multiples of 4 spaces"
-
-## Please do NOT use the `` HTML element
-
-
-
-
-Please do **NOT** start code blocks at the first column.
-
-For example:
-
-````
-``` <%%NO_COMMENT%%!---sh-->
-echo "This code block is NOT indented" <=== no thank you
-```
-````
-
-We request that you indent the code block by multiples of 4 ASCII **SPACES**:
-
-````
-``` <%%NO_COMMENT%%!---sh-->
- echo "This code block is indented by mutiples of 4 spaces"
-
- # The top level starts with a 4 ASCII space indent.
- #
- # Only indent with multiples of 4 ASCII spaces.
- # 2nd level indent needs 8 ASCII spaces (no tabs).
- # 3rd level indent needs 12 ASCII spaces (no tabs).
- # etc.
-```
+✔️ # The top level starts with a 4 ASCII space indent.
+✔️ #
+✔️ # Only indent with multiples of 4 ASCII spaces.
+✔️ # 2nd level indent needs 8 ASCII spaces (no tabs).
+✔️ # 3rd level indent needs 12 ASCII spaces (no tabs).
+✔️ # etc.
````
-Moreover:
+Alternatively its possible to use ` ``` ` marks, without the initial
+four (4) space indentation. This is usually the better method.
-````
-```
- The same thing applies to any markdown block surrounded by ``` lines.
-```
+````
+✔️ ```
+✔️ The same thing applies to any markdown block bracketed by ``` lines.
+✔️ ```
````
-Please do **NOT** indent using ASCII tab characters in markdown files.
-
-Jump to: [top](#)
+
-
-## Please do NOT use unindented code blocks
-
-
-
+## Do not use TAB in markdown files.
-Please do **NOT** indent with ASCII tabs, **OR** use any
-ASCII tab characters anywhere inside a markdown file.
+Please do **NOT** indent with ASCII TABs (␉), **OR** use any ASCII TAB
+(␉) anywhere inside a markdown file.
-While we have nothing against the ASCII tab character in general,
-we have discovered that ASCII tab characters create problems when
+While we have nothing against the ASCII TAB (␉) character in general,
+we have discovered that ASCII TAB (␉) characters create problems when
used as part of the leading whitespace within a markdown file.
-If you need to indent 2 or more levels, use multiples of 4 ASCII
-**SPACES**.
+If you need to indent two (2) or more levels, use multiples of four (4)
+ASCII SPACES.
-For example:
-
-````
+````
```
- Please do **NOT** use ASCII tabs in markdown files. <=== no thank you
- Please do **NOT** indent markdown with ASCII tabs. <=== no thank you
+❌ ␉Please do **NOT**␉use ASCII tabs␉in markdown files.
+❌ ␉␉Please do **NOT** indent markdown with ASCII tabs.
- We don't mind tabs in general, <=== no thank you
- We just ask that you NOT use them in markdown files.
+❌ ␉We don't␉mind␉tabs␉in␉general,
+❌ ␉We just ask that you NOT use them in markdown files.
```
````
-And to clarify, we are only talking about markdown files,
-not C code or any other non-markdown content:
+And to clarify, we are only talking about markdown files, not C code or
+any other non-markdown content:
-````
- printf("It is fine to use tabs in Obfuscated C code.\n");
- /* if you wish */
+````
+✔️ printf("It is fine␉to␉use tabs in Obfuscated C code.\n");
+✔️ /*␉if␉you␉wish */
- // We ask that you to NOT use ASCII tab characters in your remarks.md writeup,
- // or in any other markdown files within your entry, please.
+✔️ // We ask that you to NOT use ASCII tab characters in your remarks.md writeup,
+✔️ // or in any other markdown files within your entry, please.
````
-**NOTE**: Again, you are **perfectly welcome** to use ASCII tab characters in
-your C code and other non-markdown files. We simply ask that you do **NOT** use any
-ASCII tab characters in markdown files.
-
-Jump to: [top](#)
-
-
-## Please do NOT use ASCII tabs in markdown files
-
-
-### Tip for `vim` users
-
-
-If you use `vim` you can put in your `.vimrc` file (usually `~/.vimrc`) the
-following settings to make sure the tabs are not put in without you noticing:
-
-```
- set tabstop=8 " a tab is 8 spaces (or whatever you wish it to be set to)
- set softtabstop=4 " ...but when inserting/backspacing use 4 spaces
- set shiftwidth=4 " ...and auto-indent 4 spaces (when autoindent is set)
- set expandtab " ...expand tab into spaces
-```
-
-If you have file type detection enabled you can, if you prefer, have these
-settings set just for markdown files:
-
-```
- autocmd! Filetype markdown setlocal set tabstop=8 softtabstop=4 shiftwidth=4 expandtab
-```
-
-or so.
-
-This will prevent the tab key from inserting tabs; rather it will insert 4
-spaces.
-
-To **VERIFY** that there are no tabs in a file you may do, in command mode:
-
-```
- /\t
-```
-
-If you're in insert mode hit `ESC` first.
+**NOTE**: Again, you are **perfectly welcome** to use ASCII tab characters
+in your C code and other non-markdown files. We simply ask that
+you do **NOT** use any ASCII TAB (␉) characters in markdown files.
-Jump to: [top](#)
+
-
-
+## Use HTML comments for code block language syntax.
-We request that [fenced markdown code
-blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks)
+We request that [fenced markdown code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks)
**NOT** specify a language directly.
-For example:
-
-````
-```c <=== no thank you
- int main(void) {return 0;}
-```
+````
+❌ ```c
+❌ int main(void) {return 0;}
+❌ ```
````
Instead, put the language inside an HTML comment, separated from the
markdown code block starting fence by a space:
-````
-``` <%%NO_COMMENT%%!---c-->
- int main(void) {return 0;}
-```
+````
+✔️ ```
+✔️ int main(void) {return 0;}
+✔️ ```
````
-**IMPORTANT**: The **initial** **\` \` \`** must be followed by an **ASCII SPACE**,
-and **THEN** an **opening** **``" (two "`-`"s
+**IMPORTANT**: The **initial** **\` \` \`** must be
+followed by an **ASCII SPACE**, and **THEN** an **opening** **
+``" (two "`-`"s
followed by a "`>`").
+
-Jump to: [top](#)
-
-
-## Please use HTML comments to specify a language for a code block
-
-
-
+## Ensure blank line between code block and text.
-Please do **NOT** use a trailing slash on [void HTML
-elements](https://github.com/validator/validator/wiki/Markup-»-Void-elements).
-
-See also this note on [trailing slashes in void-element start
-tags](https://github.com/validator/validator/wiki/Markup-»-Void-elements#trailing-slashes-in-void-element-start-tags-do-NOT-mark-the-start-tags-as-self-closing).
-
-The trailing slash on void HTML elements has no effect and interacts badly with
-unquoted attribute values.
+Please do **NOT** place text on the next line after a markdown code
+block. Instead, place a blank line after the end of a markdown code
+block as this makes it easier to detect when markdown code blocks are
+**NOT** properly indented.
-For example, please do **NOT** use markdown like these:
+````
+ ```
+ int
+ main(int foo)
+ {
+ return foo;
+ }
+❌ ```
+❌ C compilers cannot be given a -Wno-main-arg-errors flag.
+
+ ```
+ int
+ main(int foo)
+ {
+ return foo;
+ }
+✔️ ```
+✔️
+✔️ C compilers cannot be given a -Wno-main-arg-errors flag.
+````
-```
-
-## Please do NOT add trailing slash to void HTML elements
-
-<=== no thank you + -
<=== no thank you +## Do not add trailing slash to void HTML tags. -
<=== no thank you
-```
+Please do **NOT** use a trailing slash on
+[void HTML elements](https://github.com/validator/validator/wiki/Markup-»-Void-elements).
-Instead use, respectively:
+See also this note on [trailing slashes in void-element start tags](https://github.com/validator/validator/wiki/Markup-»-Void-elements#trailing-slashes-in-void-element-start-tags-do-NOT-mark-the-start-tags-as-self-closing).
-```
- +The trailing slash on void HTML elements has no effect and interacts +badly with unquoted attribute values. -
+``` +❌
+❌
+❌
-
+✔️ +✔️
+✔️
```
-Jump to: [top](#)
-
-
-
+
-Unless the line is inside a markdown code block, please do **NOT**
-end a markdown line with a trailing backslash (`\`). Instead use
-a trailing `
-## Please do NOT use a TRAILING backslash (`\`) outside of a code block
-
-`. +## Do not use a trailing backslash outside of a code block -Instead of: +Unless the line is inside a markdown code block, please do **NOT** end +a markdown line with a trailing backslash (`\`). Instead use a trailing +`
`. -``` - In markdown,\ <=== no thank you - do NOT use trailing\ - backslashes outside of\ - a code block -``` +``` +❌ In markdown,\ +❌ do NOT use trailing\ +❌ backslashes outside of\ +❌ a code block -use: - -``` - In markdown,
- use trailing
- br's outside of
- a code block -``` +✔️ In markdown,
+✔️ use trailing
+✔️ br's outside of
+✔️ a code block -Again, use of a trailing backslash (`\`) inside a markdown code block is fine: +✔️ ``` +✔️ This is OK\ +✔️ inside a\ +✔️ markdown code\ +✔️ block +✔️ ``` -```` -``` - This is OK\ - inside a\ - markdown code\ - block -``` +✔️ `This is OK\` ```` -as is: - -``` - `This is OK\` -``` - -Doing it this way will prevent `pandoc(1)` from generating deprecated HTML -elements such as `
`. +Doing it this way will prevent `pandoc(1)` from generating deprecated +HTML elements such as `
`. -Jump to: [top](#) + -
-
-
-Please do **NOT** use the markdown embedded image element.
+## Do not use markdown style images
Instead of using this markdown element to embed an image:
-```
-  <=== no thank you
-```
+```
+❌ 
-Use an `
-## Please do NOT use markdown style images
-
-
-```
-
+ Which allows for HTML
-```
-
-The problem goes beyond the fact that `pandoc(1)` generates problematic
-HTML from the markdown image construct, the resulting HTML does **NOT**
-have `width` and `height` information so browsers have to slow down
-on rendering text around the image until it can internally determine
-the image size.
-
-Jump to: [top](#)
-
-
-
+## Replace markdown style horizontal lines.
Please do **NOT** use `---` style lines in markdown to create horizontal
lines or to separate sections.
-Unless something is inside a markdown **code block**, do **NOT** start a
-line with 3 or more dashes ("`-`"s).
+Unless something is inside a markdown **code block**, do **NOT** start
+a line with 3 or more dashes ("`-`"s).
-Such markdown causes `pandoc(1)` to generate `
-
-
-## Please do NOT use markdown style horizontal lines
-
-`. The `
` has no -effect in standard HTML 5 and interacts badly with unquoted attribute values. +Such markdown causes `pandoc(1)` to generate `
`. The `
` has +no effect in standard HTML 5 and interacts badly with unquoted attribute +values. If a horizontal line is really needed, use: -``` -
-``` +``` +❌ * * * +❌ - - - +❌ --- -If a short line is needed, use: + Regular divider... +✔️
-``` -
+ A short divider... +✔️
``` + -Jump to: [top](#) +## Do not put a literal "`(`" or "`)`" in markdown link titles -
-## Please do NOT put a LITERAL "`(`" or "`)`" in markdown link titles
-
+```
+❌ [some (text)](https://example.com/curds)
+✔️ [some (text)](https://example.com/curds)
-Please do **NOT** use literal parentheses inside markdown link titles.
-
-Instead of:
-
-```
- [some (text)](https://example.com/curds) <=== no thank you
-```
-
-use:
-
-```
- [some (text)](https://example.com/curds)
-```
-
-Instead of:
-
-```
- [ls(1)](https://example.com/ls-man-page.1) <=== no thank you
-```
-
-use:
-
-```
- [ls(1)](https://example.com/ls-man-page.1)
+❌ [ls(1)](https://example.com/ls-man-page.1)
+✔️ [ls(1)](https://example.com/ls-man-page.1)
```
-Jump to: [top](#)
-
-
-## Please do NOT end markdown links with "`))`"
-
+
-Please do **NOT** end a markdown link with a double closed parenthesis "`))`".
+## Do not end markdown links with "`))`"
Markdown links that end in "`))`" complicate parsing and sometimes lead
to incorrect URLs or file paths.
-Instead of:
+```
+❌ [some text](https://example.com/foo_(bar))
+✔️ [some text](https://example.com/foo_(bar))
-```
- [some text](https://example.com/foo_(bar)) <=== no thank you
+❌ This thing, ([some text](some/path)), is NOT ideal.
+✔️ This thing, [some text](some/path), is better.
```
-use:
-
-```
- [some text](https://example.com/foo_(bar))
-```
+
+## Use `_` for italics in markdown
+Please do **NOT** use `*` (single asterisk) for italics in markdown.
+Instead use an underscore (`_`). Using an asterisk can complicate
+parsing and sometimes lead to incorrect results. This can especially
+go for when it is **_bold and italic_**.
-As another example, instead of:
+```
+❌ *this text is italic*
+✔️ _this text is italic_
-```
- This thing, ([some text](some/path)), is NOT ideal. <=== no thank you
+❌ ***this text is bold italic***
+✔️ **_this text is bold italic_**
+✔️ _**this text is bold italic**_
```
-
-use:
-
-```
- This thing, [some text](some/path), is better.
-```
-
-Jump to: [top](#)
-
-
-
-
-Please do **NOT** place text on the next line after a markdown code block.
-Instead, place a blank line after the end of a markdown code block
-as this makes it easier to detect when markdown code blocks are
-**NOT** properly indented.
-
-Instead of:
-
-````
-```
- int
- main(int foo)
- {
- return foo;
- }
-```
-C compilers cannot be given a -Wno-main-arg-errors flag. <=== no thank you
-````
-
-use:
-
-````
-```
- int
- main(int foo)
- {
- return foo;
- }
-```
-
-C compilers cannot be given a -Wno-main-arg-errors flag.
-````
-
-**BTW**: Please note the blank line after the code block.
-
-Jump to: [top](#)
-
-
-
-
-## Please do NOT place text on the IMMEDIATE (very next) line after a markdown code block
-
-
-## Please use `_` for italics in markdown
-
-
-Please do **NOT** use `*` (single asterisk) for italics in markdown. Instead use
-an underscore (`_`). Using an asterisk can complicate parsing and sometimes lead
-to incorrect results. This can especially go for when it is **_bold and
-italic_**.
-
-For example, instead of:
-
-```
- *this text is italic* <=== no thank you
-```
-
-use:
-
-```
- _this text is italic_
-```
-
-Another example, for **_bold italic_**:
-
-Do **NOT** use:
-
-
-```
- ***this text is bold italic*** <=== no thank you
-```
-
-Instead use:
-
-```
- **_this text is bold italic_**
-```
-
-or:
-
-```
- _**this text is bold italic**_
-```
-
-**BTW**: the astute reader might notice that some cases of `*` for italic might
-have slipped through. We do ask you, however, to please observe this rule, as
-best you can.
+**BTW**: the astute reader might notice that some cases of `*` for
+italic might have slipped through. We do ask you, however, to please
+observe this rule, as best you can.