diff --git a/markdown.md b/markdown.md index 84a5de1a3..ea1bd103b 100644 --- a/markdown.md +++ b/markdown.md @@ -35,24 +35,34 @@ and ✔️ for preferred correct one. If (it is not required) you do use sections in your `remarks.md` file (this does not apply to other markdown files), **PLEASE** start at level three up to level six: +❌ Reserved in `remarks.md` only. ``` -❌ # Section Reserved -❌ ## Section Reserved -✔️ ### Section Level 3 -✔️ #### Section Level 4 -✔️ ##### Section Level 5 -✔️ ###### Section Level 6 +# Section Reserved +## Section Reserved +``` + +✔ Available every where. +``` +### Section Level 3 +#### Section Level 4 +##### Section Level 5 +###### Section Level 6 ```
## Replace `` construct. +❌ Incorrect. ``` -❌ ... -✔️
...
-✔️ -✔️ ### Section title +Section title +``` + +✔ Correct. +``` +
+ +### Section title ``` @@ -60,71 +70,93 @@ not apply to other markdown files), **PLEASE** start at level three up to level ## Markdown links instead of `...` +❌ Incorrect. ``` -❌ This HTML link text works, but we prefer see below... +``` + +✔ Correct. +``` +[markdown link text](#link_target) ```
## Replace `` or `` +❌ Incorrect. ``` -❌ striked through text -❌ HTML 5 striked through text +striked through text +HTML 5 striked through text +``` -✔️ HTML 5 striked through text -✔️ ~~markdown striked through text~~ +✔ Correct. +``` +~~markdown striked through text~~ +HTML 5 striked through text ```
## Replace `` +❌ Incorrect. ``` -❌ old tags -✔️ HTML 5 tags +old tags +``` + +✔ Correct. +``` +HTML 5 tags ```
## Replace `` +❌ Incorrect. ``` -❌ obsolete HTML -✔️ monospace font -✔️ `markdown style monospace` +obsolete HTML +``` + +✔ Correct. +``` +monospace font +`markdown style monospace` ```
## Indent code blocks by four spaces, not by TAB. +❌ Incorrect. ``` -❌ echo "This code block is NOT indented" +echo "This code block is NOT indented" ``` We request that you indent the code block by multiples of four (4) ASCII SPACES, never TAB (␉): +✔ Correct. ```` -✔️ echo "This code block is indented by multiples of 4 spaces" + echo "This code block is indented by multiples 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. ```` Alternatively its possible to use ` ``` ` marks, without the initial four (4) space indentation. This is usually the better method. +✔ Also correct. ```` -✔️ ``` -✔️ The same thing applies to any markdown block bracketed by ``` lines. -✔️ ``` +``` +The same thing applies to any markdown block bracketed by ``` lines. +``` ````
@@ -141,138 +173,131 @@ used as part of the leading whitespace within a markdown file. If you need to indent two (2) or more levels, use multiples of four (4) ASCII SPACES. +❌ Incorrect for markdown files only. ```` ``` -❌ ␉Please do **NOT**␉use ASCII tabs␉in markdown files. -❌ ␉␉Please do **NOT** indent markdown with ASCII tabs. +␉Please do **NOT**␉use ASCII tabs␉in markdown files. +␉␉Please do **NOT** indent markdown with ASCII tabs. -❌ ␉We␉don't␉mind␉tabs␉in␉general, -❌ ␉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: - +✔ Ok for all file types, eg. `.c`, `.h`, `.mk`, `.sh`, **EXCEPT** `.md` markdown files. ```` -✔️ ␉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. -
## Use HTML comments for code block language syntax. -We request that [fenced markdown code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) -**NOT** specify a language directly. +We request that [fenced markdown code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) **NOT** specify a language directly. +❌ Incorrect ```` -❌ ```c -❌ 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: +✔ Correct ```` -✔️ ``` -✔️ 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 -followed by a "`>`"). -
## Ensure blank line between code block and text. -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. - +❌ Incorrect, missing empty line after closing fence (` ``` `). ```` - ``` - 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. +```` - ``` - int - main(int foo) - { - return foo; - } -✔️ ``` -✔️ -✔️ C compilers cannot be given a -Wno-main-arg-errors flag. +✔ Correct, has empty line between closing fence and subsequent text. +```` +``` +int +main(int foo) +{ + return foo; +} +``` + +C compilers cannot be given a -Wno-main-arg-errors flag. ````
## Do not add trailing slash to void HTML tags. -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. +The trailing slash on [void HTML elements](https://github.com/validator/validator/wiki/Markup-»-Void-elements) has no effect and interacts +badly with unquoted attribute values; do not use. 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). + +❌ Incorrect ``` -❌
-❌
-❌ image of a tattoo of
-   the 1984 anonymous C code +
+
+image of a tattoo of
+the 1984 anonymous C code +``` -✔️
-✔️
-✔️ image of a tattoo of
-   the 1984 anonymous C code +✔ Correct +``` +
+
+image of a tattoo of
+the 1984 anonymous C code ```
## Do not use a trailing backslash outside of a code block -Unless the line is inside a markdown code block, please do **NOT** end -a markdown line with a trailing backslash (`\`). Instead use a trailing -`
`. - +❌ Incorrect, do not use escaped newlines outside of a code block. ``` -❌ In markdown,\ -❌ do NOT use trailing\ -❌ backslashes outside of\ -❌ a code block +In markdown,\ +do NOT use trailing\ +backslashes outside of\ +a code block +``` -✔️ In markdown,
-✔️ use trailing
-✔️ br's outside of
-✔️ a code block +✔ Correct +```` +In markdown,
+use trailing
+br's outside of
+a code block -✔️ ``` -✔️ This is OK\ -✔️ inside a\ -✔️ markdown code\ -✔️ block -✔️ ``` +``` +This is OK\ +inside a\ +markdown code\ +block +``` -✔️ `This is OK\` +`This is OK\` ```` Doing it this way will prevent `pandoc(1)` from generating deprecated @@ -282,16 +307,18 @@ HTML elements, such as `
`. ## Do not use markdown style images -Instead of using this markdown element to embed an image: - +❌ Incorrect ``` -❌ ![alt text](filename.png "Title") +![alt text](filename.png "Title") +``` -✔️ describe the filename.png image for someone who cannot view it +✔ Correct +``` + - Which allows for HTML attributes `alt=`, `width=` and `length=`. +Which allows for HTML attributes `alt=`, `width=` and `length=`. ``` The problem is that `pandoc(1)` generates problematic HTML from the @@ -313,28 +340,36 @@ Such markdown causes `pandoc(1)` to generate `
`. The `
` has no effect in standard HTML 5 and interacts badly with unquoted attribute values. +❌ Incorrect ``` -❌ * * * -❌ - - - -❌ --- +* * * +- - - +--- +``` - Regular divider... -✔️
+✔ Correct +``` +Regular divider... +
- A short divider... -✔️
+A short divider... +
```
## Do not put a literal "`(`" or "`)`" in markdown link titles +❌ Incorrect ``` -❌ [some (text)](https://example.com/curds) -✔️ [some (text)](https://example.com/curds) +[some (text)](https://example.com/curds) +[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) +✔ Correct +``` +[some (text)](https://example.com/curds) +[ls(1)](https://example.com/ls-man-page.1) ```
@@ -344,12 +379,16 @@ values. Markdown links that end in "`))`" complicate parsing and sometimes lead to incorrect URLs or file paths. +❌ Incorrect ``` -❌ [some text](https://example.com/foo_(bar)) -✔️ [some text](https://example.com/foo_(bar)) +[some text](https://example.com/foo_(bar)) +This thing, ([some text](some/path)), is NOT ideal. +``` -❌ This thing, ([some text](some/path)), is NOT ideal. -✔️ This thing, [some text](some/path), is better. +✔ Correct +``` +[some text](https://example.com/foo_(bar)) +This thing, [some text](some/path), is better. ```
@@ -361,13 +400,17 @@ 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_**. +❌ Incorrect ``` -❌ *this text is italic* -✔️ _this text is italic_ +*this text is italic* +***this text is bold italic*** +``` -❌ ***this text is bold italic*** -✔️ **_this text is bold italic_** -✔️ _**this text is bold italic**_ +✔ Correct +``` +_this text is italic_ +**_this text is bold italic_** +_**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