improve markdown
Fixed a number of whitespace, HTML comments, intending, and markdown problems. Clarified the <!---language--> syntax. Made a number of textual changes to be more consistent. Replaced emoji with HTML symbols. Misc cleanup. Ran `make markdown sitemap` to perform the above.
This commit is contained in:
Landon Curt Noll committed
1 parent
8ef10b3df6
commit
b19846fb4d
3 files changed
+454
-348
No files matched your search
+181
-151
@@ -454,10 +454,7 @@
|
||||
<!-- BEFORE: 1st line of markdown file: markdown.md -->
|
||||
<h1 id="ioccc-29th-markdown-guidelines">IOCCC 29th Markdown Guidelines</h1>
|
||||
<h2 id="markdown-guidelines-version">Markdown Guidelines Version</h2>
|
||||
<p>These <a href="markdown.html">Markdown Guidelines</a> are version <strong>29.0 2025-11-26</strong>.</p>
|
||||
<div id="introduction">
|
||||
|
||||
</div>
|
||||
<p>These <a href="markdown.html">Markdown Guidelines</a> are version <strong>29.01 2025-11-28</strong>.</p>
|
||||
<h2 id="introduction">Introduction</h2>
|
||||
<p>The IOCCC makes extensive use of <a href="https://daringfireball.net/projects/markdown/">markdown</a>. For example, when
|
||||
submitting to the IOCCC we have people submit remarks about their
|
||||
@@ -467,7 +464,8 @@ that entry. All HTML 5 generated pages on the <a href="https://www.ioccc.org/ind
|
||||
start with some markdown content. We no longer support older HTML
|
||||
standards and some of our guidelines help integrate winning entries into
|
||||
the website more easily.</p>
|
||||
<p>See the <a href="https://www.markdownguide.org/basic-syntax">markdown syntax</a> guide. See also the <a href="https://spec.commonmark.org/current/">CommonMark Spec</a>.
|
||||
<p>See the <a href="https://www.markdownguide.org/basic-syntax">markdown syntax</a> guide.
|
||||
See also the <a href="https://spec.commonmark.org/current/">CommonMark Spec</a>.
|
||||
See the FAQ on “<a href="faq.html#remarks_md">remarks.md submission file</a>”.</p>
|
||||
<p>Nevertheless, the IOCCC does have certain practices that we ask authors to
|
||||
follow. Some of these relate to use of markdown directly and others relate
|
||||
@@ -481,31 +479,31 @@ and ✔️ for preferred correct one.</p>
|
||||
<p>If (it is not required) you do use sections in your <code>remarks.md</code> file (this does
|
||||
not apply to other markdown files), <strong>PLEASE</strong> start at level three up to level six:</p>
|
||||
<p><span style="color:red">❌</span> Reserved in <code>remarks.md</code> only.</p>
|
||||
<pre class="<!---markdown-->"><code># Section Reserved
|
||||
## Section Reserved</code></pre>
|
||||
<p><span style="color:green">✔</span> Available every where.</p>
|
||||
<pre><code>### Section Level 3
|
||||
#### Section Level 4
|
||||
##### Section Level 5
|
||||
###### Section Level 6</code></pre>
|
||||
<pre><code> # Section Reserved
|
||||
## Section Reserved</code></pre>
|
||||
<p><span style="color:green">✅</span> Available every where.</p>
|
||||
<pre><code> ### Section Level 3
|
||||
#### Section Level 4
|
||||
##### Section Level 5
|
||||
###### Section Level 6</code></pre>
|
||||
<div id="anchor-name">
|
||||
|
||||
</div>
|
||||
<h2 id="replace-a-nameanchor_namea-construct.">Replace <code><a name="anchor_name"></a></code> construct.</h2>
|
||||
<h2 id="replace-a-nameanchor_namea-construct">Replace <code><a name="anchor_name"></a></code> construct</h2>
|
||||
<p><span style="color:red">❌</span> Incorrect.</p>
|
||||
<pre class="<!---html-->"><code><a name="old_way">Section title</a></code></pre>
|
||||
<p><span style="color:green">✔</span> Correct.</p>
|
||||
<pre class="<!---html-->"><code><div id="new_way"></div>
|
||||
<pre><code> <a name="old_way">Section title</a></code></pre>
|
||||
<p><span style="color:green">✅</span> Correct.</p>
|
||||
<pre><code> <div id="new_way"></div>
|
||||
|
||||
### Section title</code></pre>
|
||||
### Section title</code></pre>
|
||||
<div id="links">
|
||||
|
||||
</div>
|
||||
<h2 id="markdown-links-instead-of-a...a">Markdown links instead of <code><a>...</a></code></h2>
|
||||
<p><span style="color:red">❌</span> Incorrect.</p>
|
||||
<pre class="<!---html-->"><code>This <a href="#link_target>HTML link text</a> works, but we prefer see below...</code></pre>
|
||||
<p><span style="color:green">✔</span> Correct.</p>
|
||||
<pre class="<!---html-->"><code>[markdown link text](#link_target)</code></pre>
|
||||
<pre><code> This <a href="#link_target>HTML link text</a> works, but we prefer see below...</code></pre>
|
||||
<p><span style="color:green">✅</span> Correct.</p>
|
||||
<pre><code> [markdown link text](#link_target)</code></pre>
|
||||
<div id="del">
|
||||
|
||||
</div>
|
||||
@@ -514,11 +512,11 @@ not apply to other markdown files), <strong>PLEASE</strong> start at level three
|
||||
</div>
|
||||
<h2 id="replace-strike-or-s">Replace <code><strike></code> or <code><s></code></h2>
|
||||
<p><span style="color:red">❌</span> Incorrect.</p>
|
||||
<pre class="<!---html-->"><code><strike>striked through text</strike>
|
||||
<s>HTML 5 striked through text</s></code></pre>
|
||||
<p><span style="color:green">✔</span> Correct.</p>
|
||||
<pre class="<!---html-->"><code>~~markdown striked through text~~
|
||||
<del>HTML 5 striked through text</del></code></pre>
|
||||
<pre><code> <strike>striked through text</strike>
|
||||
<s>HTML 5 striked through text</s></code></pre>
|
||||
<p><span style="color:green">✅</span> Correct.</p>
|
||||
<pre><code> ~~markdown striked through text~~
|
||||
<del>HTML 5 striked through text</del></code></pre>
|
||||
<div id="ins">
|
||||
|
||||
</div>
|
||||
@@ -527,48 +525,69 @@ not apply to other markdown files), <strong>PLEASE</strong> start at level three
|
||||
</div>
|
||||
<h2 id="replace-u">Replace <code><u></code></h2>
|
||||
<p><span style="color:red">❌</span> Incorrect.</p>
|
||||
<pre class="<!---html-->"><code><u>old tags</u></code></pre>
|
||||
<p><span style="color:green">✔</span> Correct.</p>
|
||||
<pre class="<!---html-->"><code><ins>HTML 5 tags</ins></code></pre>
|
||||
<pre><code> <u>old tags</u></code></pre>
|
||||
<p><span style="color:green">✅</span> Correct.</p>
|
||||
<pre><code> <ins>HTML 5 tags</ins></code></pre>
|
||||
<div id="tt">
|
||||
|
||||
</div>
|
||||
<h2 id="replace-tt">Replace <code><tt></code></h2>
|
||||
<p><span style="color:red">❌</span> Incorrect.</p>
|
||||
<pre class="<!---html-->"><code><tt>obsolete HTML</tt></code></pre>
|
||||
<p><span style="color:green">✔</span> Correct.</p>
|
||||
<pre class="<!---html-->"><code><span style="font-family: monospace;">monospace font</span>
|
||||
`markdown style monospace`</code></pre>
|
||||
<pre><code> <tt>obsolete HTML</tt></code></pre>
|
||||
<p><span style="color:green">✅</span> Correct.</p>
|
||||
<pre><code> <span style="font-family: monospace;">monospace font</span>
|
||||
`markdown style monospace`</code></pre>
|
||||
<div id="indent">
|
||||
|
||||
</div>
|
||||
<h2 id="indent-code-blocks-by-four-spaces-not-by-tab.">Indent code blocks by four spaces, not by TAB.</h2>
|
||||
<h2 id="indent-code-blocks-by-four-spaces-not-by-tab">Indent code blocks by four spaces, not by TAB</h2>
|
||||
<p><span style="color:red">❌</span> Incorrect.</p>
|
||||
<pre class="<!---sh-->"><code>echo "This code block is NOT indented"</code></pre>
|
||||
<pre class="<!---markdown-->"><code> ``` <!---sh-->
|
||||
echo "This shell code block is NOT properly indented!"
|
||||
echo 'Please indent your code blocks with multiples of four (4) ASCII SPACES!"
|
||||
```</code></pre>
|
||||
<p>We request that you indent the code block by multiples of four (4)
|
||||
ASCII SPACES, never TAB (␉):</p>
|
||||
<p><span style="color:green">✔</span> Correct.</p>
|
||||
<pre class="<!---sh-->"><code> echo "This code block is indented by multiples of 4 spaces"
|
||||
<p><span style="color:green">✅</span> Correct.</p>
|
||||
<pre class="<!---markdown-->"><code> ``` <!---sh-->
|
||||
echo "This shell code block is indented by multiples of 4 spaces"
|
||||
```</code></pre>
|
||||
<p>If you need to intent more than one level, use multiples of 4 ASCII spaces (no tabs):</p>
|
||||
<p><span style="color:green">✅</span> Also Correct.</p>
|
||||
<pre class="<!---markdown-->"><code> ``` <!---sh-->
|
||||
echo "This shell 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.</code></pre>
|
||||
<p>Alternatively its possible to use <code>```</code> marks, without the initial
|
||||
four (4) space indentation. This is usually the better method.</p>
|
||||
<p><span style="color:green">✔</span> Also correct.</p>
|
||||
<pre class="<!---markdown-->"><code>```
|
||||
The same thing applies to any markdown block bracketed by ``` lines.
|
||||
```</code></pre>
|
||||
for i in $(seq 1 9); do
|
||||
echo "This 2nd level is intented by 8 spaces (no tabs)"
|
||||
if [[ $i -gt 5 ]]; then
|
||||
echo "This 3rd level is intented by 12 spaces (no tabs)"
|
||||
break
|
||||
fi
|
||||
done
|
||||
```</code></pre>
|
||||
<p>While it is possible to use 3 backticks (```) without the initial
|
||||
four (4) space indentation, we <strong>prefer</strong> that you multiples of 4 spaces if possible:</p>
|
||||
<p><span style="color:green">✅</span> Preferred.</p>
|
||||
<pre class="<!---markdown-->"><code> ```
|
||||
Intent text by multiples of 4 spaces if possible.
|
||||
```</code></pre>
|
||||
<p>A reasonable exception to the rule is when are displaying C:</p>
|
||||
<p><span style="color:green">✅</span> OK for C.</p>
|
||||
<pre class="<!---markdown-->"><code> ``` <!---c-->
|
||||
/* not intending C code is OK */
|
||||
int
|
||||
bar(int foo)
|
||||
{
|
||||
return foo;
|
||||
}
|
||||
```</code></pre>
|
||||
<div id="tabs">
|
||||
|
||||
</div>
|
||||
<div id="spaces">
|
||||
|
||||
</div>
|
||||
<h2 id="do-not-use-tab-in-markdown-files.">Do not use TAB in markdown files.</h2>
|
||||
<h2 id="do-not-use-tab-in-markdown-files">Do not use TAB in markdown files</h2>
|
||||
<p>Please do <strong>NOT</strong> indent with ASCII TABs (␉), <strong>OR</strong> use any ASCII TAB
|
||||
(␉) anywhere inside a markdown file.</p>
|
||||
<p>While we have nothing against the ASCII TAB (␉) character in general,
|
||||
@@ -577,77 +596,88 @@ used as part of the leading whitespace within a markdown file.</p>
|
||||
<p>If you need to indent two (2) or more levels, use multiples of four (4)
|
||||
ASCII SPACES.</p>
|
||||
<p><span style="color:red">❌</span> Incorrect for markdown files only.</p>
|
||||
<pre class="<!---markdown-->"><code>```
|
||||
␉Please do **NOT**␉use ASCII tabs␉in markdown files.
|
||||
␉␉Please do **NOT** indent markdown with ASCII tabs.
|
||||
<pre class="<!---markdown-->"><code> ```
|
||||
␉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.
|
||||
```</code></pre>
|
||||
<p><span style="color:green">✔</span> Ok for all file types, eg. <code>.c</code>, <code>.h</code>, <code>.mk</code>, <code>.sh</code>, <strong>EXCEPT</strong> <code>.md</code> markdown files.</p>
|
||||
<pre class="<!---c-->"><code>␉printf("It is fine␉to␉use tabs in Obfuscated C code.\n");
|
||||
␉␉/*␉if␉you␉wish */
|
||||
␉We␉don't␉mind␉tabs␉in␉general,
|
||||
␉We just ask that you NOT use them in markdown files.
|
||||
```</code></pre>
|
||||
<p><span style="color:green">✅</span> OK for all file types, e.g., <code>.c</code>, <code>.h</code>, <code>.mk</code>, <code>.sh</code>, <strong>EXCEPT</strong> <code>.md</code> markdown files.</p>
|
||||
<pre class="<!---c-->"><code> ␉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.</code></pre>
|
||||
␉// 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.</code></pre>
|
||||
<p><strong>NOTE</strong>: For purposes of visual illustration, ASCII TABs are shown above with the <code>␉</code> symbol.</p>
|
||||
<div id="code">
|
||||
|
||||
</div>
|
||||
<div id="languages">
|
||||
|
||||
</div>
|
||||
<h2 id="use-html-comments-for-code-block-language-syntax.">Use HTML comments for code block language syntax.</h2>
|
||||
<h2 id="use-html-comments-for-code-block-language-syntax">Use HTML comments for code block language syntax</h2>
|
||||
<p>We request that <a href="https://www.markdownguide.org/extended-syntax/#fenced-code-blocks">fenced markdown code blocks</a> <strong>NOT</strong> specify a language directly.</p>
|
||||
<p><span style="color:red">❌</span> Incorrect</p>
|
||||
<pre class="<!---markdown-->"><code>```c
|
||||
int main(void) {return 0;}
|
||||
```</code></pre>
|
||||
<p><span style="color:red">❌</span> Incorrect.</p>
|
||||
<pre class="<!---markdown-->"><code> ```c
|
||||
int main(void) {return 0;}
|
||||
```</code></pre>
|
||||
<p>Instead, put the language inside an HTML comment, separated from the
|
||||
markdown code block starting fence by a space:</p>
|
||||
<p><span style="color:green">✔</span> Correct</p>
|
||||
<pre class="<!---markdown-->"><code>```<!---c-->
|
||||
int main(void) {return 0;}
|
||||
```</code></pre>
|
||||
<p><span style="color:green">✅</span> Correct.</p>
|
||||
<pre class="<!---markdown-->"><code> ``` <!---c-->
|
||||
int main(void) {return 0;}
|
||||
```</code></pre>
|
||||
<p><strong>PLEASE NOTE</strong>: There is an <strong>IMPORTANT</strong> ASCII SPACE between the 3 backticks (```)
|
||||
and the start of the HTML comment!</p>
|
||||
<p><strong>PLEASE</strong>: Use an HTML comment that is of this form:</p>
|
||||
<ul>
|
||||
<li>starts with <code><!---</code> (note the 3 dashes)</li>
|
||||
<li>is immediately followed by the language</li>
|
||||
<li>and finally followed by <code>--></code> (note the 2 dashes)</li>
|
||||
</ul>
|
||||
<div id="code-and-text">
|
||||
|
||||
</div>
|
||||
<h2 id="ensure-blank-line-between-code-block-and-text.">Ensure blank line between code block and text.</h2>
|
||||
<p><span style="color:red">❌</span> Incorrect, missing empty line after closing fence (<code>```</code>).</p>
|
||||
<pre class="<!---markdown-->"><code>```
|
||||
int
|
||||
main(int foo)
|
||||
{
|
||||
return foo;
|
||||
}
|
||||
```
|
||||
C compilers cannot be given a -Wno-main-arg-errors flag.</code></pre>
|
||||
<p><span style="color:green">✔</span> Correct, has empty line between closing fence and subsequent text.</p>
|
||||
<pre class="<!---markdown-->"><code>```
|
||||
int
|
||||
main(int foo)
|
||||
{
|
||||
return foo;
|
||||
}
|
||||
```
|
||||
<h2 id="ensure-blank-line-between-code-block-and-text">Ensure blank line between code block and text</h2>
|
||||
<p><span style="color:red">❌</span> Incorrect, missing empty line after closing 3 backtick (```) fence.</p>
|
||||
<pre class="<!---markdown-->"><code> ``` <!---c-->
|
||||
/* The C compiler will insist in flagging this an error, unfortunately */
|
||||
int
|
||||
main(int foo)
|
||||
{
|
||||
return foo;
|
||||
}
|
||||
```
|
||||
C compilers cannot be given a -Wno-main-arg-errors flag.</code></pre>
|
||||
<p><span style="color:green">✅</span> Correct, has empty line between closing fence and subsequent text.</p>
|
||||
<pre class="<!---markdown-->"><code> ``` <!---c-->
|
||||
/* The C compiler will insist in flagging this an error, unfortunately */
|
||||
int
|
||||
main(int foo)
|
||||
{
|
||||
return foo;
|
||||
}
|
||||
```
|
||||
|
||||
C compilers cannot be given a -Wno-main-arg-errors flag.</code></pre>
|
||||
C compilers cannot be given a -Wno-main-arg-errors flag.</code></pre>
|
||||
<div id="tag-slash">
|
||||
|
||||
</div>
|
||||
<h2 id="do-not-add-trailing-slash-to-void-html-tags.">Do not add trailing slash to void HTML tags.</h2>
|
||||
<h2 id="do-not-add-trailing-slash-to-void-html-tags">Do not add trailing slash to void HTML tags</h2>
|
||||
<p>The trailing slash on <a href="https://github.com/validator/validator/wiki/Markup-»-Void-elements">void HTML elements</a> has no effect and interacts
|
||||
badly with unquoted attribute values; do not use. See also this note
|
||||
on <a href="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">trailing slashes in void-element start tags</a>.</p>
|
||||
<p><span style="color:red">❌</span> Incorrect</p>
|
||||
<pre class="<!---html-->"><code><br/>
|
||||
<hr/>
|
||||
<img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of
|
||||
the 1984 anonymous C code" width=600 height=401 /></code></pre>
|
||||
<p><span style="color:green">✔</span> Correct</p>
|
||||
<pre class="<!---html-->"><code><br>
|
||||
<hr>
|
||||
<img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of
|
||||
the 1984 anonymous C code" width=600 height=401></code></pre>
|
||||
<p><span style="color:red">❌</span> Incorrect.</p>
|
||||
<pre><code> <br/>
|
||||
<hr/>
|
||||
<img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of
|
||||
the 1984 anonymous C code" width=600 height=401 /></code></pre>
|
||||
<p><span style="color:green">✅</span> Correct.</p>
|
||||
<pre><code> <br>
|
||||
<hr>
|
||||
<img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of
|
||||
the 1984 anonymous C code" width=600 height=401></code></pre>
|
||||
<div id="br">
|
||||
|
||||
</div>
|
||||
@@ -656,38 +686,38 @@ the 1984 anonymous C code" width=600 height=401></code></pre>
|
||||
</div>
|
||||
<h2 id="do-not-use-a-trailing-backslash-outside-of-a-code-block">Do not use a trailing backslash outside of a code block</h2>
|
||||
<p><span style="color:red">❌</span> Incorrect, do not use escaped newlines outside of a code block.</p>
|
||||
<pre class="<!---markdown-->"><code>In markdown,\
|
||||
do NOT use trailing\
|
||||
backslashes outside of\
|
||||
a code block</code></pre>
|
||||
<p><span style="color:green">✔</span> Correct</p>
|
||||
<pre class="<!---html-->"><code>In markdown,<br>
|
||||
use trailing<br>
|
||||
br's outside of<br>
|
||||
a code block
|
||||
<pre><code> In markdown,\
|
||||
do NOT use trailing\
|
||||
backslashes outside of\
|
||||
a code block</code></pre>
|
||||
<p><span style="color:green">✅</span> Correct.</p>
|
||||
<pre class="<!---html-->"><code> In markdown,<br>
|
||||
use trailing<br>
|
||||
br's outside of<br>
|
||||
a code block
|
||||
|
||||
```
|
||||
This is OK\
|
||||
inside a\
|
||||
markdown code\
|
||||
block
|
||||
```
|
||||
```
|
||||
This is OK\
|
||||
inside a\
|
||||
markdown code\
|
||||
block
|
||||
```
|
||||
|
||||
`This is OK\`</code></pre>
|
||||
`This is OK\`</code></pre>
|
||||
<p>Doing it this way will prevent <code>pandoc(1)</code> from generating deprecated
|
||||
HTML elements, such as <code><br /></code>.</p>
|
||||
<div id="img">
|
||||
|
||||
</div>
|
||||
<h2 id="do-not-use-markdown-style-images">Do not use markdown style images</h2>
|
||||
<p><span style="color:red">❌</span> Incorrect</p>
|
||||
<pre class="<!---markdown-->"><code></code></pre>
|
||||
<p><span style="color:green">✔</span> Correct</p>
|
||||
<pre class="<!---markdown-->"><code><img src="filename.png"
|
||||
alt="describe the filename.png image for someone who cannot view it"
|
||||
width=PIXEL_WIDTH height=PIXEL_HEIGHT>
|
||||
<p><span style="color:red">❌</span> Incorrect.</p>
|
||||
<pre><code> </code></pre>
|
||||
<p><span style="color:green">✅</span> Correct.</p>
|
||||
<pre><code> <img src="filename.png"
|
||||
alt="describe the filename.png image for someone who cannot view it"
|
||||
width=PIXEL_WIDTH height=PIXEL_HEIGHT>
|
||||
|
||||
Which allows for HTML <img> attributes `alt=`, `width=` and `length=`.</code></pre>
|
||||
Which allows for HTML <img> attributes `alt=`, `width=` and `length=`.</code></pre>
|
||||
<p>The problem is that <code>pandoc(1)</code> generates problematic HTML from the
|
||||
markdown image construct, the resulting HTML does <strong>NOT</strong> have <code>width</code>
|
||||
and <code>height</code> information so browsers have to slow down on rendering
|
||||
@@ -695,7 +725,7 @@ text around the image until it can internally determine the image size.</p>
|
||||
<div id="hr">
|
||||
|
||||
</div>
|
||||
<h2 id="replace-markdown-style-horizontal-lines.">Replace markdown style horizontal lines.</h2>
|
||||
<h2 id="replace-markdown-style-horizontal-lines">Replace markdown style horizontal lines</h2>
|
||||
<p>Please do <strong>NOT</strong> use <code>---</code> style lines in markdown to create horizontal
|
||||
lines or to separate sections.</p>
|
||||
<p>Unless something is inside a markdown <strong>code block</strong>, do <strong>NOT</strong> start
|
||||
@@ -703,38 +733,38 @@ a line with 3 or more dashes (“<code>-</code>”s).</p>
|
||||
<p>Such markdown causes <code>pandoc(1)</code> to generate <code><hr /></code>. The <code><hr /></code> has
|
||||
no effect in standard HTML 5 and interacts badly with unquoted attribute
|
||||
values.</p>
|
||||
<p><span style="color:red">❌</span> Incorrect</p>
|
||||
<pre class="<!---html-->"><code>* * *
|
||||
- - -
|
||||
---</code></pre>
|
||||
<p><span style="color:green">✔</span> Correct</p>
|
||||
<pre class="<!---html-->"><code>Regular divider...
|
||||
<hr>
|
||||
<p><span style="color:red">❌</span> Incorrect.</p>
|
||||
<pre><code> * * *
|
||||
- - -
|
||||
---</code></pre>
|
||||
<p><span style="color:green">✅</span> Correct.</p>
|
||||
<pre><code> Regular divider...
|
||||
<hr>
|
||||
|
||||
A short divider...
|
||||
<hr style="width:10%;text-align:left;margin-left:0"></code></pre>
|
||||
A short divider...
|
||||
<hr style="width:10%;text-align:left;margin-left:0"></code></pre>
|
||||
<div id="parentheses">
|
||||
|
||||
</div>
|
||||
<h2 id="do-not-put-a-literal-or-in-markdown-link-titles">Do not put a literal “<code>(</code>” or “<code>)</code>” in markdown link titles</h2>
|
||||
<p><span style="color:red">❌</span> Incorrect</p>
|
||||
<pre class="<!---markdown-->"><code>[some (text)](https://example.com/curds)
|
||||
[ls(1)](https://example.com/ls-man-page.1)</code></pre>
|
||||
<p><span style="color:green">✔</span> Correct</p>
|
||||
<pre class="<!---markdown-->"><code>[some &lpar;text&rpar;](https://example.com/curds)
|
||||
[ls&lpar;1&rpar;](https://example.com/ls-man-page.1)</code></pre>
|
||||
<p><span style="color:red">❌</span> Incorrect.</p>
|
||||
<pre><code> [some (text)](https://example.com/curds)
|
||||
[ls(1)](https://example.com/ls-man-page.1)</code></pre>
|
||||
<p><span style="color:green">✅</span> Correct.</p>
|
||||
<pre><code> [some &lpar;text&rpar;](https://example.com/curds)
|
||||
[ls&lpar;1&rpar;](https://example.com/ls-man-page.1)</code></pre>
|
||||
<div id="closing-parentheses">
|
||||
|
||||
</div>
|
||||
<h2 id="do-not-end-markdown-links-with">Do not end markdown links with “<code>))</code>”</h2>
|
||||
<p>Markdown links that end in “<code>))</code>” complicate parsing and sometimes lead
|
||||
to incorrect URLs or file paths.</p>
|
||||
<p><span style="color:red">❌</span> Incorrect</p>
|
||||
<pre class="<!---markdown-->"><code>[some text](https://example.com/foo_(bar))
|
||||
This thing, ([some text](some/path)), is NOT ideal.</code></pre>
|
||||
<p><span style="color:green">✔</span> Correct</p>
|
||||
<pre class="<!---markdown-->"><code>[some text](https://example.com/foo_&lpar;bar&rpar;)
|
||||
This thing, [some text](some/path), is better.</code></pre>
|
||||
<p><span style="color:red">❌</span> Incorrect.</p>
|
||||
<pre><code> [some text](https://example.com/foo_(bar))
|
||||
This thing, ([some text](some/path)), is NOT ideal.</code></pre>
|
||||
<p><span style="color:green">✅</span> Correct.</p>
|
||||
<pre><code> [some text](https://example.com/foo_&lpar;bar&rpar;)
|
||||
This thing, [some text](some/path), is better.</code></pre>
|
||||
<div id="italics">
|
||||
|
||||
</div>
|
||||
@@ -743,13 +773,13 @@ This thing, [some text](some/path), is better.</code></pre>
|
||||
Instead use an underscore (<code>_</code>). Using an asterisk can complicate
|
||||
parsing and sometimes lead to incorrect results. This can especially
|
||||
go for when it is <strong><em>bold and italic</em></strong>.</p>
|
||||
<p><span style="color:red">❌</span> Incorrect</p>
|
||||
<pre class="<!---markdown-->"><code>*this text is italic*
|
||||
***this text is bold italic***</code></pre>
|
||||
<p><span style="color:green">✔</span> Correct</p>
|
||||
<pre class="<!---markdown-->"><code>_this text is italic_
|
||||
**_this text is bold italic_**
|
||||
_**this text is bold italic**_</code></pre>
|
||||
<p><span style="color:red">❌</span> Incorrect.</p>
|
||||
<pre><code> *this text is italic*
|
||||
***this text is bold italic***</code></pre>
|
||||
<p><span style="color:green">✅</span> Correct.</p>
|
||||
<pre><code> _this text is italic_
|
||||
**_this text is bold italic_**
|
||||
_**this text is bold italic**_</code></pre>
|
||||
<p><strong>BTW</strong>: the astute reader might notice that some cases of <code>*</code> for italic
|
||||
might have slipped through. We do ask you, however, to please
|
||||
observe this rule, as best you can.
|
||||
|
||||
+271
-195
@@ -1,11 +1,10 @@
|
||||
|
||||
# IOCCC 29th Markdown Guidelines
|
||||
|
||||
|
||||
## Markdown Guidelines Version
|
||||
|
||||
These [Markdown Guidelines](markdown.html) are version **29.0 2025-11-26**.
|
||||
These [Markdown Guidelines](markdown.html) are version **29.01 2025-11-28**.
|
||||
|
||||
<div id="introduction"></div>
|
||||
|
||||
## Introduction
|
||||
|
||||
@@ -18,150 +17,196 @@ start with some markdown content. We no longer support older HTML
|
||||
standards and some of our guidelines help integrate winning entries into
|
||||
the website more easily.
|
||||
|
||||
See the [markdown syntax](https://www.markdownguide.org/basic-syntax) guide. See also the [CommonMark Spec](https://spec.commonmark.org/current/).
|
||||
See the [markdown syntax](https://www.markdownguide.org/basic-syntax) guide.
|
||||
See also the [CommonMark Spec](https://spec.commonmark.org/current/).
|
||||
See the FAQ on "[remarks.md submission file](faq.html#remarks_md)".
|
||||
|
||||
Nevertheless, the IOCCC does have certain practices that we ask authors to
|
||||
follow. Some of these relate to use of markdown directly and others relate
|
||||
to injecting HTML into the markdown file.
|
||||
|
||||
In the sections below, examples will mark by ❌ for the incorrect method
|
||||
In the sections below, examples will mark by ❌ for the incorrect method
|
||||
and ✔️ for preferred correct one.
|
||||
|
||||
|
||||
<div id="sections"></div>
|
||||
|
||||
|
||||
## Start `remarks.md` sections at level 3
|
||||
|
||||
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:
|
||||
|
||||
<span style="color:red">❌</span> Reserved in `remarks.md` only.
|
||||
```<!---markdown-->
|
||||
# Section Reserved
|
||||
## Section Reserved
|
||||
<span style="color:red">❌</span> Reserved in `remarks.md` only.
|
||||
``` <!---markdown-->
|
||||
# Section Reserved
|
||||
## Section Reserved
|
||||
```
|
||||
|
||||
<span style="color:green">✔</span> Available every where.
|
||||
<span style="color:green">✅</span> Available every where.
|
||||
```
|
||||
### Section Level 3
|
||||
#### Section Level 4
|
||||
##### Section Level 5
|
||||
###### Section Level 6
|
||||
### Section Level 3
|
||||
#### Section Level 4
|
||||
##### Section Level 5
|
||||
###### Section Level 6
|
||||
```
|
||||
|
||||
|
||||
<div id="anchor-name"></div>
|
||||
|
||||
## Replace `<a name="anchor_name"></a>` construct.
|
||||
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
```<!---html-->
|
||||
<a name="old_way">Section title</a>
|
||||
## Replace `<a name="anchor_name"></a>` construct
|
||||
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
``` <!---html-->
|
||||
<a name="old_way">Section title</a>
|
||||
```
|
||||
|
||||
<span style="color:green">✔</span> Correct.
|
||||
```<!---html-->
|
||||
<div id="new_way"></div>
|
||||
<span style="color:green">✅</span> Correct.
|
||||
``` <!---html-->
|
||||
<div id="new_way"></div>
|
||||
|
||||
### Section title
|
||||
### Section title
|
||||
```
|
||||
|
||||
|
||||
<div id="links"></div>
|
||||
|
||||
|
||||
## Markdown links instead of `<a>...</a>`
|
||||
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
```<!---html-->
|
||||
This <a href="#link_target>HTML link text</a> works, but we prefer see below...
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
``` <!---html-->
|
||||
This <a href="#link_target>HTML link text</a> works, but we prefer see below...
|
||||
```
|
||||
|
||||
<span style="color:green">✔</span> Correct.
|
||||
```<!---html-->
|
||||
[markdown link text](#link_target)
|
||||
<span style="color:green">✅</span> Correct.
|
||||
``` <!---html-->
|
||||
[markdown link text](#link_target)
|
||||
```
|
||||
|
||||
|
||||
<div id="del"></div><div id="strike"></div>
|
||||
|
||||
|
||||
## Replace `<strike>` or `<s>`
|
||||
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
```<!---html-->
|
||||
<strike>striked through text</strike>
|
||||
<s>HTML 5 striked through text</s>
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
``` <!---html-->
|
||||
<strike>striked through text</strike>
|
||||
<s>HTML 5 striked through text</s>
|
||||
```
|
||||
|
||||
<span style="color:green">✔</span> Correct.
|
||||
```<!---html-->
|
||||
~~markdown striked through text~~
|
||||
<del>HTML 5 striked through text</del>
|
||||
<span style="color:green">✅</span> Correct.
|
||||
``` <!---html-->
|
||||
~~markdown striked through text~~
|
||||
<del>HTML 5 striked through text</del>
|
||||
```
|
||||
|
||||
|
||||
<div id="ins"></div><div id="underline"></div>
|
||||
|
||||
|
||||
## Replace `<u>`
|
||||
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
```<!---html-->
|
||||
<u>old tags</u>
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
``` <!---html-->
|
||||
<u>old tags</u>
|
||||
```
|
||||
|
||||
<span style="color:green">✔</span> Correct.
|
||||
```<!---html-->
|
||||
<ins>HTML 5 tags</ins>
|
||||
<span style="color:green">✅</span> Correct.
|
||||
``` <!---html-->
|
||||
<ins>HTML 5 tags</ins>
|
||||
```
|
||||
|
||||
|
||||
<div id="tt"></div>
|
||||
|
||||
|
||||
## Replace `<tt>`
|
||||
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
```<!---html-->
|
||||
<tt>obsolete HTML</tt>
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
``` <!---html-->
|
||||
<tt>obsolete HTML</tt>
|
||||
```
|
||||
|
||||
<span style="color:green">✔</span> Correct.
|
||||
```<!---html-->
|
||||
<span style="font-family: monospace;">monospace font</span>
|
||||
`markdown style monospace`
|
||||
<span style="color:green">✅</span> Correct.
|
||||
``` <!---html-->
|
||||
<span style="font-family: monospace;">monospace font</span>
|
||||
`markdown style monospace`
|
||||
```
|
||||
|
||||
|
||||
<div id="indent"></div>
|
||||
|
||||
## Indent code blocks by four spaces, not by TAB.
|
||||
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
```<!---sh-->
|
||||
echo "This code block is NOT indented"
|
||||
## Indent code blocks by four spaces, not by TAB
|
||||
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
```` <!---markdown-->
|
||||
``` <!---sh-->
|
||||
echo "This shell code block is NOT properly indented!"
|
||||
echo 'Please indent your code blocks with multiples of four (4) ASCII SPACES!"
|
||||
```
|
||||
````
|
||||
|
||||
We request that you indent the code block by multiples of four (4)
|
||||
ASCII SPACES, never TAB (␉):
|
||||
|
||||
<span style="color:green">✔</span> Correct.
|
||||
````<!---sh-->
|
||||
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.
|
||||
<span style="color:green">✅</span> Correct.
|
||||
```` <!---markdown-->
|
||||
``` <!---sh-->
|
||||
echo "This shell code block is indented by multiples of 4 spaces"
|
||||
```
|
||||
````
|
||||
|
||||
Alternatively its possible to use ` ``` ` marks, without the initial
|
||||
four (4) space indentation. This is usually the better method.
|
||||
If you need to intent more than one level, use multiples of 4 ASCII spaces (no tabs):
|
||||
|
||||
<span style="color:green">✔</span> Also correct.
|
||||
````<!---markdown-->
|
||||
```
|
||||
The same thing applies to any markdown block bracketed by ``` lines.
|
||||
```
|
||||
<span style="color:green">✅</span> Also Correct.
|
||||
```` <!---markdown-->
|
||||
``` <!---sh-->
|
||||
echo "This shell code block is indented by multiples of 4 spaces"
|
||||
|
||||
for i in $(seq 1 9); do
|
||||
echo "This 2nd level is intented by 8 spaces (no tabs)"
|
||||
if [[ $i -gt 5 ]]; then
|
||||
echo "This 3rd level is intented by 12 spaces (no tabs)"
|
||||
break
|
||||
fi
|
||||
done
|
||||
```
|
||||
````
|
||||
|
||||
While it is possible to use 3 backticks (```) without the initial
|
||||
four (4) space indentation, we **prefer** that you multiples of 4 spaces if possible:
|
||||
|
||||
<span style="color:green">✅</span> Preferred.
|
||||
```` <!---markdown-->
|
||||
```
|
||||
Intent text by multiples of 4 spaces if possible.
|
||||
```
|
||||
````
|
||||
|
||||
A reasonable exception to the rule is when are displaying C:
|
||||
|
||||
<span style="color:green">✅</span> OK for C.
|
||||
|
||||
```` <!---markdown-->
|
||||
``` <!---c-->
|
||||
/* not intending C code is OK */
|
||||
int
|
||||
bar(int foo)
|
||||
{
|
||||
return foo;
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
|
||||
<div id="tabs"></div><div id="spaces"></div>
|
||||
|
||||
## Do not use TAB in markdown files.
|
||||
|
||||
## Do not use TAB in markdown files
|
||||
|
||||
Please do **NOT** indent with ASCII TABs (␉), **OR** use any ASCII TAB
|
||||
(␉) anywhere inside a markdown file.
|
||||
@@ -173,152 +218,174 @@ 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.
|
||||
|
||||
<span style="color:red">❌</span> Incorrect for markdown files only.
|
||||
````<!---markdown-->
|
||||
```
|
||||
␉Please do **NOT**␉use ASCII tabs␉in markdown files.
|
||||
␉␉Please do **NOT** indent markdown with ASCII tabs.
|
||||
<span style="color:red">❌</span> Incorrect for markdown files only.
|
||||
```` <!---markdown-->
|
||||
```
|
||||
␉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.
|
||||
```
|
||||
````
|
||||
|
||||
<span style="color:green">✔</span> Ok for all file types, eg. `.c`, `.h`, `.mk`, `.sh`, **EXCEPT** `.md` markdown files.
|
||||
````<!---c-->
|
||||
␉printf("It is fine␉to␉use tabs in Obfuscated C code.\n");
|
||||
␉␉/*␉if␉you␉wish */
|
||||
<span style="color:green">✅</span> OK for all file types, e.g., `.c`, `.h`, `.mk`, `.sh`, **EXCEPT** `.md` markdown files.
|
||||
```` <!---c-->
|
||||
␉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**: For purposes of visual illustration, ASCII TABs are shown above with the `␉` symbol.
|
||||
|
||||
|
||||
<div id="code"></div><div id="languages"></div>
|
||||
|
||||
## Use HTML comments for code block language syntax.
|
||||
|
||||
## 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.
|
||||
|
||||
<span style="color:red">❌</span> Incorrect
|
||||
````<!---markdown-->
|
||||
```c
|
||||
int main(void) {return 0;}
|
||||
```
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
```` <!---markdown-->
|
||||
```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:
|
||||
|
||||
<span style="color:green">✔</span> Correct
|
||||
````<!---markdown-->
|
||||
```<!---c-->
|
||||
int main(void) {return 0;}
|
||||
```
|
||||
<span style="color:green">✅</span> Correct.
|
||||
```` <!---markdown-->
|
||||
``` <!---c-->
|
||||
int main(void) {return 0;}
|
||||
```
|
||||
````
|
||||
|
||||
**PLEASE NOTE**: There is an **IMPORTANT** ASCII SPACE between the 3 backticks (```)
|
||||
and the start of the HTML comment!
|
||||
|
||||
**PLEASE**: Use an HTML comment that is of this form:
|
||||
|
||||
* starts with `<!---` (note the 3 dashes)
|
||||
* is immediately followed by the language
|
||||
* and finally followed by `-->` (note the 2 dashes)
|
||||
|
||||
|
||||
<div id="code-and-text"></div>
|
||||
|
||||
## Ensure blank line between code block and text.
|
||||
|
||||
<span style="color:red">❌</span> Incorrect, missing empty line after closing fence (` ``` `).
|
||||
````<!---markdown-->
|
||||
```
|
||||
int
|
||||
main(int foo)
|
||||
{
|
||||
return foo;
|
||||
}
|
||||
```
|
||||
C compilers cannot be given a -Wno-main-arg-errors flag.
|
||||
## Ensure blank line between code block and text
|
||||
|
||||
<span style="color:red">❌</span> Incorrect, missing empty line after closing 3 backtick (```) fence.
|
||||
```` <!---markdown-->
|
||||
``` <!---c-->
|
||||
/* The C compiler will insist in flagging this an error, unfortunately */
|
||||
int
|
||||
main(int foo)
|
||||
{
|
||||
return foo;
|
||||
}
|
||||
```
|
||||
C compilers cannot be given a -Wno-main-arg-errors flag.
|
||||
````
|
||||
|
||||
<span style="color:green">✔</span> Correct, has empty line between closing fence and subsequent text.
|
||||
````<!---markdown-->
|
||||
```
|
||||
int
|
||||
main(int foo)
|
||||
{
|
||||
return foo;
|
||||
}
|
||||
```
|
||||
<span style="color:green">✅</span> Correct, has empty line between closing fence and subsequent text.
|
||||
```` <!---markdown-->
|
||||
``` <!---c-->
|
||||
/* The C compiler will insist in flagging this an error, unfortunately */
|
||||
int
|
||||
main(int foo)
|
||||
{
|
||||
return foo;
|
||||
}
|
||||
```
|
||||
|
||||
C compilers cannot be given a -Wno-main-arg-errors flag.
|
||||
C compilers cannot be given a -Wno-main-arg-errors flag.
|
||||
````
|
||||
|
||||
|
||||
<div id="tag-slash"></div>
|
||||
|
||||
## Do not add trailing slash to void HTML tags.
|
||||
|
||||
## Do not add trailing slash to void HTML tags
|
||||
|
||||
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).
|
||||
|
||||
|
||||
<span style="color:red">❌</span> Incorrect
|
||||
```<!---html-->
|
||||
<br/>
|
||||
<hr/>
|
||||
<img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of
|
||||
the 1984 anonymous C code" width=600 height=401 />
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
``` <!---html-->
|
||||
<br/>
|
||||
<hr/>
|
||||
<img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of
|
||||
the 1984 anonymous C code" width=600 height=401 />
|
||||
```
|
||||
|
||||
<span style="color:green">✔</span> Correct
|
||||
```<!---html-->
|
||||
<br>
|
||||
<hr>
|
||||
<img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of
|
||||
the 1984 anonymous C code" width=600 height=401>
|
||||
<span style="color:green">✅</span> Correct.
|
||||
``` <!---html-->
|
||||
<br>
|
||||
<hr>
|
||||
<img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of
|
||||
the 1984 anonymous C code" width=600 height=401>
|
||||
```
|
||||
|
||||
|
||||
<div id="br"></div><div id="backslash"></div>
|
||||
|
||||
|
||||
## Do not use a trailing backslash outside of a code block
|
||||
|
||||
<span style="color:red">❌</span> Incorrect, do not use escaped newlines outside of a code block.
|
||||
```<!---markdown-->
|
||||
In markdown,\
|
||||
do NOT use trailing\
|
||||
backslashes outside of\
|
||||
a code block
|
||||
<span style="color:red">❌</span> Incorrect, do not use escaped newlines outside of a code block.
|
||||
``` <!---markdown-->
|
||||
In markdown,\
|
||||
do NOT use trailing\
|
||||
backslashes outside of\
|
||||
a code block
|
||||
```
|
||||
|
||||
<span style="color:green">✔</span> Correct
|
||||
````<!---html-->
|
||||
In markdown,<br>
|
||||
use trailing<br>
|
||||
br's outside of<br>
|
||||
a code block
|
||||
<span style="color:green">✅</span> Correct.
|
||||
```` <!---html-->
|
||||
In markdown,<br>
|
||||
use trailing<br>
|
||||
br's outside of<br>
|
||||
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
|
||||
HTML elements, such as `<br />`.
|
||||
|
||||
|
||||
<div id="img"></div>
|
||||
|
||||
|
||||
## Do not use markdown style images
|
||||
|
||||
<span style="color:red">❌</span> Incorrect
|
||||
```<!---markdown-->
|
||||
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
``` <!---markdown-->
|
||||
|
||||
```
|
||||
|
||||
<span style="color:green">✔</span> Correct
|
||||
```<!---markdown-->
|
||||
<img src="filename.png"
|
||||
alt="describe the filename.png image for someone who cannot view it"
|
||||
width=PIXEL_WIDTH height=PIXEL_HEIGHT>
|
||||
<span style="color:green">✅</span> Correct.
|
||||
``` <!---markdown-->
|
||||
<img src="filename.png"
|
||||
alt="describe the filename.png image for someone who cannot view it"
|
||||
width=PIXEL_WIDTH height=PIXEL_HEIGHT>
|
||||
|
||||
Which allows for HTML <img> attributes `alt=`, `width=` and `length=`.
|
||||
Which allows for HTML <img> attributes `alt=`, `width=` and `length=`.
|
||||
```
|
||||
|
||||
The problem is that `pandoc(1)` generates problematic HTML from the
|
||||
@@ -326,9 +393,11 @@ 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.
|
||||
|
||||
|
||||
<div id="hr"></div>
|
||||
|
||||
## Replace markdown style horizontal lines.
|
||||
|
||||
## Replace markdown style horizontal lines
|
||||
|
||||
Please do **NOT** use `---` style lines in markdown to create horizontal
|
||||
lines or to separate sections.
|
||||
@@ -340,59 +409,65 @@ Such markdown causes `pandoc(1)` to generate `<hr />`. The `<hr />` has
|
||||
no effect in standard HTML 5 and interacts badly with unquoted attribute
|
||||
values.
|
||||
|
||||
<span style="color:red">❌</span> Incorrect
|
||||
```<!---html-->
|
||||
* * *
|
||||
- - -
|
||||
---
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
``` <!---html-->
|
||||
* * *
|
||||
- - -
|
||||
---
|
||||
```
|
||||
|
||||
<span style="color:green">✔</span> Correct
|
||||
```<!---html-->
|
||||
Regular divider...
|
||||
<hr>
|
||||
<span style="color:green">✅</span> Correct.
|
||||
``` <!---html-->
|
||||
Regular divider...
|
||||
<hr>
|
||||
|
||||
A short divider...
|
||||
<hr style="width:10%;text-align:left;margin-left:0">
|
||||
A short divider...
|
||||
<hr style="width:10%;text-align:left;margin-left:0">
|
||||
```
|
||||
|
||||
|
||||
<div id="parentheses"></div>
|
||||
|
||||
|
||||
## Do not put a literal "`(`" or "`)`" in markdown link titles
|
||||
|
||||
<span style="color:red">❌</span> Incorrect
|
||||
```<!---markdown-->
|
||||
[some (text)](https://example.com/curds)
|
||||
[ls(1)](https://example.com/ls-man-page.1)
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
``` <!---markdown-->
|
||||
[some (text)](https://example.com/curds)
|
||||
[ls(1)](https://example.com/ls-man-page.1)
|
||||
```
|
||||
|
||||
<span style="color:green">✔</span> Correct
|
||||
```<!---markdown-->
|
||||
[some (text)](https://example.com/curds)
|
||||
[ls(1)](https://example.com/ls-man-page.1)
|
||||
<span style="color:green">✅</span> Correct.
|
||||
``` <!---markdown-->
|
||||
[some (text)](https://example.com/curds)
|
||||
[ls(1)](https://example.com/ls-man-page.1)
|
||||
```
|
||||
|
||||
|
||||
<div id="closing-parentheses"></div>
|
||||
|
||||
|
||||
## Do not end markdown links with "`))`"
|
||||
|
||||
Markdown links that end in "`))`" complicate parsing and sometimes lead
|
||||
to incorrect URLs or file paths.
|
||||
|
||||
<span style="color:red">❌</span> Incorrect
|
||||
```<!---markdown-->
|
||||
[some text](https://example.com/foo_(bar))
|
||||
This thing, ([some text](some/path)), is NOT ideal.
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
``` <!---markdown-->
|
||||
[some text](https://example.com/foo_(bar))
|
||||
This thing, ([some text](some/path)), is NOT ideal.
|
||||
```
|
||||
|
||||
<span style="color:green">✔</span> Correct
|
||||
```<!---markdown-->
|
||||
[some text](https://example.com/foo_(bar))
|
||||
This thing, [some text](some/path), is better.
|
||||
<span style="color:green">✅</span> Correct.
|
||||
``` <!---markdown-->
|
||||
[some text](https://example.com/foo_(bar))
|
||||
This thing, [some text](some/path), is better.
|
||||
```
|
||||
|
||||
|
||||
<div id="italics"></div>
|
||||
|
||||
|
||||
## Use `_` for italics in markdown
|
||||
|
||||
Please do **NOT** use `*` (single asterisk) for italics in markdown.
|
||||
@@ -400,18 +475,19 @@ 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_**.
|
||||
|
||||
<span style="color:red">❌</span> Incorrect
|
||||
```<!---markdown-->
|
||||
*this text is italic*
|
||||
***this text is bold italic***
|
||||
<span style="color:red">❌</span> Incorrect.
|
||||
``` <!---markdown-->
|
||||
*this text is italic*
|
||||
***this text is bold italic***
|
||||
```
|
||||
|
||||
<span style="color:green">✔</span> Correct
|
||||
```<!---markdown-->
|
||||
_this text is italic_
|
||||
**_this text is bold italic_**
|
||||
_**this text is bold italic**_
|
||||
<span style="color:green">✅</span> Correct.
|
||||
``` <!---markdown-->
|
||||
_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
|
||||
observe this rule, as best you can.
|
||||
+2
-2
@@ -16810,11 +16810,11 @@
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://www.ioccc.org/markdown.html</loc>
|
||||
<lastmod>2025-11-28T05:02:34+00:00</lastmod>
|
||||
<lastmod>2025-11-28T16:46:49+00:00</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://www.ioccc.org/markdown.md</loc>
|
||||
<lastmod>2025-11-28T04:59:17+00:00</lastmod>
|
||||
<lastmod>2025-11-28T16:46:44+00:00</lastmod>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://www.ioccc.org/news.html</loc>
|
||||
|
||||
Reference in new issue
Block a user