mirror/ioccc
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

improve markdown

Browse Source 
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 2025-11-28 08:47:33 -08:00
1 parent 8ef10b3df6
commit b19846fb4d
3 files changed
+454 -348
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

markdown.html
+181 -151
View File
@@ -454,10 +454,7 @@
<!-- BEFORE: 1st line of markdown file: markdown.md --> <!-- BEFORE: 1st line of markdown file: markdown.md -->
<h1 id="ioccc-29th-markdown-guidelines">IOCCC 29th Markdown Guidelines</h1> <h1 id="ioccc-29th-markdown-guidelines">IOCCC 29th Markdown Guidelines</h1>
<h2 id="markdown-guidelines-version">Markdown Guidelines Version</h2> <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> <p>These <a href="markdown.html">Markdown Guidelines</a> are version <strong>29.01 2025-11-28</strong>.</p>
<div id="introduction">
</div>
<h2 id="introduction">Introduction</h2> <h2 id="introduction">Introduction</h2>
<p>The IOCCC makes extensive use of <a href="https://daringfireball.net/projects/markdown/">markdown</a>. For example, when <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 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 start with some markdown content. We no longer support older HTML
standards and some of our guidelines help integrate winning entries into standards and some of our guidelines help integrate winning entries into
the website more easily.</p> 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> 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 <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 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 <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> 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> <p><span style="color:red">❌</span> Reserved in <code>remarks.md</code> only.</p>
<pre class="&lt;!---markdown--&gt;"><code># Section Reserved <pre><code> # Section Reserved
## Section Reserved</code></pre> ## Section Reserved</code></pre>
<p><span style="color:green">✔</span> Available every where.</p> <p><span style="color:green">✅</span> Available every where.</p>
<pre><code>### Section Level 3 <pre><code> ### Section Level 3
#### Section Level 4 #### Section Level 4
##### Section Level 5 ##### Section Level 5
###### Section Level 6</code></pre> ###### Section Level 6</code></pre>
<div id="anchor-name"> <div id="anchor-name">
</div> </div>
<h2 id="replace-a-nameanchor_namea-construct.">Replace <code>&lt;a name="anchor_name"&gt;&lt;/a&gt;</code> construct.</h2> <h2 id="replace-a-nameanchor_namea-construct">Replace <code>&lt;a name="anchor_name"&gt;&lt;/a&gt;</code> construct</h2>
<p><span style="color:red">❌</span> Incorrect.</p> <p><span style="color:red">❌</span> Incorrect.</p>
<pre class="&lt;!---html--&gt;"><code>&lt;a name=&quot;old_way&quot;&gt;Section title&lt;/a&gt;</code></pre> <pre><code> &lt;a name=&quot;old_way&quot;&gt;Section title&lt;/a&gt;</code></pre>
<p><span style="color:green">✔</span> Correct.</p> <p><span style="color:green">✅</span> Correct.</p>
<pre class="&lt;!---html--&gt;"><code>&lt;div id=&quot;new_way&quot;&gt;&lt;/div&gt; <pre><code> &lt;div id=&quot;new_way&quot;&gt;&lt;/div&gt;
### Section title</code></pre> ### Section title</code></pre>
<div id="links"> <div id="links">
</div> </div>
<h2 id="markdown-links-instead-of-a...a">Markdown links instead of <code>&lt;a&gt;...&lt;/a&gt;</code></h2> <h2 id="markdown-links-instead-of-a...a">Markdown links instead of <code>&lt;a&gt;...&lt;/a&gt;</code></h2>
<p><span style="color:red">❌</span> Incorrect.</p> <p><span style="color:red">❌</span> Incorrect.</p>
<pre class="&lt;!---html--&gt;"><code>This &lt;a href=&quot;#link_target&gt;HTML link text&lt;/a&gt; works, but we prefer see below...</code></pre> <pre><code> This &lt;a href=&quot;#link_target&gt;HTML link text&lt;/a&gt; works, but we prefer see below...</code></pre>
<p><span style="color:green">✔</span> Correct.</p> <p><span style="color:green">✅</span> Correct.</p>
<pre class="&lt;!---html--&gt;"><code>[markdown link text](#link_target)</code></pre> <pre><code> [markdown link text](#link_target)</code></pre>
<div id="del"> <div id="del">
</div> </div>
@@ -514,11 +512,11 @@ not apply to other markdown files), <strong>PLEASE</strong> start at level three
</div> </div>
<h2 id="replace-strike-or-s">Replace <code>&lt;strike&gt;</code> or <code>&lt;s&gt;</code></h2> <h2 id="replace-strike-or-s">Replace <code>&lt;strike&gt;</code> or <code>&lt;s&gt;</code></h2>
<p><span style="color:red">❌</span> Incorrect.</p> <p><span style="color:red">❌</span> Incorrect.</p>
<pre class="&lt;!---html--&gt;"><code>&lt;strike&gt;striked through text&lt;/strike&gt; <pre><code> &lt;strike&gt;striked through text&lt;/strike&gt;
&lt;s&gt;HTML 5 striked through text&lt;/s&gt;</code></pre> &lt;s&gt;HTML 5 striked through text&lt;/s&gt;</code></pre>
<p><span style="color:green">✔</span> Correct.</p> <p><span style="color:green">✅</span> Correct.</p>
<pre class="&lt;!---html--&gt;"><code>~~markdown striked through text~~ <pre><code> ~~markdown striked through text~~
&lt;del&gt;HTML 5 striked through text&lt;/del&gt;</code></pre> &lt;del&gt;HTML 5 striked through text&lt;/del&gt;</code></pre>
<div id="ins"> <div id="ins">
</div> </div>
@@ -527,48 +525,69 @@ not apply to other markdown files), <strong>PLEASE</strong> start at level three
</div> </div>
<h2 id="replace-u">Replace <code>&lt;u&gt;</code></h2> <h2 id="replace-u">Replace <code>&lt;u&gt;</code></h2>
<p><span style="color:red">❌</span> Incorrect.</p> <p><span style="color:red">❌</span> Incorrect.</p>
<pre class="&lt;!---html--&gt;"><code>&lt;u&gt;old tags&lt;/u&gt;</code></pre> <pre><code> &lt;u&gt;old tags&lt;/u&gt;</code></pre>
<p><span style="color:green">✔</span> Correct.</p> <p><span style="color:green">✅</span> Correct.</p>
<pre class="&lt;!---html--&gt;"><code>&lt;ins&gt;HTML 5 tags&lt;/ins&gt;</code></pre> <pre><code> &lt;ins&gt;HTML 5 tags&lt;/ins&gt;</code></pre>
<div id="tt"> <div id="tt">
</div> </div>
<h2 id="replace-tt">Replace <code>&lt;tt&gt;</code></h2> <h2 id="replace-tt">Replace <code>&lt;tt&gt;</code></h2>
<p><span style="color:red">❌</span> Incorrect.</p> <p><span style="color:red">❌</span> Incorrect.</p>
<pre class="&lt;!---html--&gt;"><code>&lt;tt&gt;obsolete HTML&lt;/tt&gt;</code></pre> <pre><code> &lt;tt&gt;obsolete HTML&lt;/tt&gt;</code></pre>
<p><span style="color:green">✔</span> Correct.</p> <p><span style="color:green">✅</span> Correct.</p>
<pre class="&lt;!---html--&gt;"><code>&lt;span style=&quot;font-family: monospace;&quot;&gt;monospace font&lt;/span&gt; <pre><code> &lt;span style=&quot;font-family: monospace;&quot;&gt;monospace font&lt;/span&gt;
`markdown style monospace`</code></pre> `markdown style monospace`</code></pre>
<div id="indent"> <div id="indent">
</div> </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> <p><span style="color:red">❌</span> Incorrect.</p>
<pre class="&lt;!---sh--&gt;"><code>echo &quot;This code block is NOT indented&quot;</code></pre> <pre class="&lt;!---markdown--&gt;"><code> ``` &lt;!---sh--&gt;
echo &quot;This shell code block is NOT properly indented!&quot;
echo &#39;Please indent your code blocks with multiples of four (4) ASCII SPACES!&quot;
```</code></pre>
<p>We request that you indent the code block by multiples of four (4) <p>We request that you indent the code block by multiples of four (4)
ASCII SPACES, never TAB (␉):</p> ASCII SPACES, never TAB (␉):</p>
<p><span style="color:green">✔</span> Correct.</p> <p><span style="color:green">✅</span> Correct.</p>
<pre class="&lt;!---sh--&gt;"><code> echo &quot;This code block is indented by multiples of 4 spaces&quot; <pre class="&lt;!---markdown--&gt;"><code> ``` &lt;!---sh--&gt;
echo &quot;This shell code block is indented by multiples of 4 spaces&quot;
```</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="&lt;!---markdown--&gt;"><code> ``` &lt;!---sh--&gt;
echo &quot;This shell code block is indented by multiples of 4 spaces&quot;
# The top level starts with a 4 ASCII space indent. for i in $(seq 1 9); do
# echo &quot;This 2nd level is intented by 8 spaces (no tabs)&quot;
# Only indent with multiples of 4 ASCII spaces. if [[ $i -gt 5 ]]; then
# 2nd level indent needs 8 ASCII spaces (no tabs). echo &quot;This 3rd level is intented by 12 spaces (no tabs)&quot;
# 3rd level indent needs 12 ASCII spaces (no tabs). break
# etc.</code></pre> fi
<p>Alternatively its possible to use <code>```</code> marks, without the initial done
four (4) space indentation. This is usually the better method.</p> ```</code></pre>
<p><span style="color:green">✔</span> Also correct.</p> <p>While it is possible to use 3 backticks (```) without the initial
<pre class="&lt;!---markdown--&gt;"><code>``` four (4) space indentation, we <strong>prefer</strong> that you multiples of 4 spaces if possible:</p>
The same thing applies to any markdown block bracketed by ``` lines. <p><span style="color:green">✅</span> Preferred.</p>
```</code></pre> <pre class="&lt;!---markdown--&gt;"><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="&lt;!---markdown--&gt;"><code> ``` &lt;!---c--&gt;
/* not intending C code is OK */
int
bar(int foo)
{
return foo;
}
```</code></pre>
<div id="tabs"> <div id="tabs">
</div> </div>
<div id="spaces"> <div id="spaces">
</div> </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 <p>Please do <strong>NOT</strong> indent with ASCII TABs (␉), <strong>OR</strong> use any ASCII TAB
(␉) anywhere inside a markdown file.</p> (␉) anywhere inside a markdown file.</p>
<p>While we have nothing against the ASCII TAB (␉) character in general, <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) <p>If you need to indent two (2) or more levels, use multiples of four (4)
ASCII SPACES.</p> ASCII SPACES.</p>
<p><span style="color:red">❌</span> Incorrect for markdown files only.</p> <p><span style="color:red">❌</span> Incorrect for markdown files only.</p>
<pre class="&lt;!---markdown--&gt;"><code>``` <pre class="&lt;!---markdown--&gt;"><code> ```
␉Please do **NOT**␉use ASCII tabs␉in markdown files. ␉Please do **NOT**␉use ASCII tabs␉in markdown files.
␉␉Please do **NOT** indent markdown with ASCII tabs. ␉␉Please do **NOT** indent markdown with ASCII tabs.
␉We␉don&#39;t␉mind␉tabs␉in␉general, ␉We␉don&#39;t␉mind␉tabs␉in␉general,
␉We just ask that you NOT use them in markdown files. ␉We just ask that you NOT use them in markdown files.
```</code></pre> ```</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> <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="&lt;!---c--&gt;"><code>␉printf(&quot;It is fine␉to␉use tabs in Obfuscated C code.\n&quot;); <pre class="&lt;!---c--&gt;"><code> ␉printf(&quot;It is fine␉to␉use tabs in Obfuscated C code.\n&quot;);
␉␉/*␉if␉you␉wish */ ␉␉/*␉if␉you␉wish */
␉// We ask that you to NOT use ASCII tab characters in your remarks.md writeup, ␉// 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> ␉// 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 id="code">
</div> </div>
<div id="languages"> <div id="languages">
</div> </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>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> <p><span style="color:red">❌</span> Incorrect.</p>
<pre class="&lt;!---markdown--&gt;"><code>```c <pre class="&lt;!---markdown--&gt;"><code> ```c
int main(void) {return 0;} int main(void) {return 0;}
```</code></pre> ```</code></pre>
<p>Instead, put the language inside an HTML comment, separated from the <p>Instead, put the language inside an HTML comment, separated from the
markdown code block starting fence by a space:</p> markdown code block starting fence by a space:</p>
<p><span style="color:green">✔</span> Correct</p> <p><span style="color:green">✅</span> Correct.</p>
<pre class="&lt;!---markdown--&gt;"><code>```&lt;!---c--&gt; <pre class="&lt;!---markdown--&gt;"><code> ``` &lt;!---c--&gt;
int main(void) {return 0;} int main(void) {return 0;}
```</code></pre> ```</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>&lt;!---</code> (note the 3 dashes)</li>
<li>is immediately followed by the language</li>
<li>and finally followed by <code>--&gt;</code> (note the 2 dashes)</li>
</ul>
<div id="code-and-text"> <div id="code-and-text">
</div> </div>
<h2 id="ensure-blank-line-between-code-block-and-text.">Ensure blank line between code block and text.</h2> <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> <p><span style="color:red">❌</span> Incorrect, missing empty line after closing 3 backtick (```) fence.</p>
<pre class="&lt;!---markdown--&gt;"><code>``` <pre class="&lt;!---markdown--&gt;"><code> ``` &lt;!---c--&gt;
int /* The C compiler will insist in flagging this an error, unfortunately */
main(int foo) int
{ main(int foo)
return 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> C compilers cannot be given a -Wno-main-arg-errors flag.</code></pre>
<pre class="&lt;!---markdown--&gt;"><code>``` <p><span style="color:green">✅</span> Correct, has empty line between closing fence and subsequent text.</p>
int <pre class="&lt;!---markdown--&gt;"><code> ``` &lt;!---c--&gt;
main(int foo) /* The C compiler will insist in flagging this an error, unfortunately */
{ int
return foo; 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 id="tag-slash">
</div> </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 <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 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> 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> <p><span style="color:red">❌</span> Incorrect.</p>
<pre class="&lt;!---html--&gt;"><code>&lt;br/&gt; <pre><code> &lt;br/&gt;
&lt;hr/&gt; &lt;hr/&gt;
&lt;img src=&quot;1984-anonymous-tattoo.jpg&quot; alt=&quot;image of a tattoo of &lt;img src=&quot;1984-anonymous-tattoo.jpg&quot; alt=&quot;image of a tattoo of
the 1984 anonymous C code&quot; width=600 height=401 /&gt;</code></pre> the 1984 anonymous C code&quot; width=600 height=401 /&gt;</code></pre>
<p><span style="color:green">✔</span> Correct</p> <p><span style="color:green">✅</span> Correct.</p>
<pre class="&lt;!---html--&gt;"><code>&lt;br&gt; <pre><code> &lt;br&gt;
&lt;hr&gt; &lt;hr&gt;
&lt;img src=&quot;1984-anonymous-tattoo.jpg&quot; alt=&quot;image of a tattoo of &lt;img src=&quot;1984-anonymous-tattoo.jpg&quot; alt=&quot;image of a tattoo of
the 1984 anonymous C code&quot; width=600 height=401&gt;</code></pre> the 1984 anonymous C code&quot; width=600 height=401&gt;</code></pre>
<div id="br"> <div id="br">
</div> </div>
@@ -656,38 +686,38 @@ the 1984 anonymous C code&quot; width=600 height=401&gt;</code></pre>
</div> </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> <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> <p><span style="color:red">❌</span> Incorrect, do not use escaped newlines outside of a code block.</p>
<pre class="&lt;!---markdown--&gt;"><code>In markdown,\ <pre><code> In markdown,\
do NOT use trailing\ do NOT use trailing\
backslashes outside of\ backslashes outside of\
a code block</code></pre> a code block</code></pre>
<p><span style="color:green">✔</span> Correct</p> <p><span style="color:green">✅</span> Correct.</p>
<pre class="&lt;!---html--&gt;"><code>In markdown,&lt;br&gt; <pre class="&lt;!---html--&gt;"><code> In markdown,&lt;br&gt;
use trailing&lt;br&gt; use trailing&lt;br&gt;
br&#39;s outside of&lt;br&gt; br&#39;s outside of&lt;br&gt;
a code block a code block
``` ```
This is OK\ This is OK\
inside a\ inside a\
markdown code\ markdown code\
block 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 <p>Doing it this way will prevent <code>pandoc(1)</code> from generating deprecated
HTML elements, such as <code>&lt;br /&gt;</code>.</p> HTML elements, such as <code>&lt;br /&gt;</code>.</p>
<div id="img"> <div id="img">
</div> </div>
<h2 id="do-not-use-markdown-style-images">Do not use markdown style images</h2> <h2 id="do-not-use-markdown-style-images">Do not use markdown style images</h2>
<p><span style="color:red">❌</span> Incorrect</p> <p><span style="color:red">❌</span> Incorrect.</p>
<pre class="&lt;!---markdown--&gt;"><code>![alt text](filename.png &quot;Title&quot;)</code></pre> <pre><code> ![alt text](filename.png &quot;Title&quot;)</code></pre>
<p><span style="color:green">✔</span> Correct</p> <p><span style="color:green">✅</span> Correct.</p>
<pre class="&lt;!---markdown--&gt;"><code>&lt;img src=&quot;filename.png&quot; <pre><code> &lt;img src=&quot;filename.png&quot;
alt=&quot;describe the filename.png image for someone who cannot view it&quot; alt=&quot;describe the filename.png image for someone who cannot view it&quot;
width=PIXEL_WIDTH height=PIXEL_HEIGHT&gt; width=PIXEL_WIDTH height=PIXEL_HEIGHT&gt;
Which allows for HTML &lt;img&gt; attributes `alt=`, `width=` and `length=`.</code></pre> Which allows for HTML &lt;img&gt; attributes `alt=`, `width=` and `length=`.</code></pre>
<p>The problem is that <code>pandoc(1)</code> generates problematic HTML from the <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> 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 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 id="hr">
</div> </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 <p>Please do <strong>NOT</strong> use <code>---</code> style lines in markdown to create horizontal
lines or to separate sections.</p> lines or to separate sections.</p>
<p>Unless something is inside a markdown <strong>code block</strong>, do <strong>NOT</strong> start <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>&lt;hr /&gt;</code>. The <code>&lt;hr /&gt;</code> has <p>Such markdown causes <code>pandoc(1)</code> to generate <code>&lt;hr /&gt;</code>. The <code>&lt;hr /&gt;</code> has
no effect in standard HTML 5 and interacts badly with unquoted attribute no effect in standard HTML 5 and interacts badly with unquoted attribute
values.</p> values.</p>
<p><span style="color:red">❌</span> Incorrect</p> <p><span style="color:red">❌</span> Incorrect.</p>
<pre class="&lt;!---html--&gt;"><code>* * * <pre><code> * * *
- - - - - -
---</code></pre> ---</code></pre>
<p><span style="color:green">✔</span> Correct</p> <p><span style="color:green">✅</span> Correct.</p>
<pre class="&lt;!---html--&gt;"><code>Regular divider... <pre><code> Regular divider...
&lt;hr&gt; &lt;hr&gt;
A short divider... A short divider...
&lt;hr style=&quot;width:10%;text-align:left;margin-left:0&quot;&gt;</code></pre> &lt;hr style=&quot;width:10%;text-align:left;margin-left:0&quot;&gt;</code></pre>
<div id="parentheses"> <div id="parentheses">
</div> </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> <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> <p><span style="color:red">❌</span> Incorrect.</p>
<pre class="&lt;!---markdown--&gt;"><code>[some (text)](https://example.com/curds) <pre><code> [some (text)](https://example.com/curds)
[ls(1)](https://example.com/ls-man-page.1)</code></pre> [ls(1)](https://example.com/ls-man-page.1)</code></pre>
<p><span style="color:green">✔</span> Correct</p> <p><span style="color:green">✅</span> Correct.</p>
<pre class="&lt;!---markdown--&gt;"><code>[some &amp;lpar;text&amp;rpar;](https://example.com/curds) <pre><code> [some &amp;lpar;text&amp;rpar;](https://example.com/curds)
[ls&amp;lpar;1&amp;rpar;](https://example.com/ls-man-page.1)</code></pre> [ls&amp;lpar;1&amp;rpar;](https://example.com/ls-man-page.1)</code></pre>
<div id="closing-parentheses"> <div id="closing-parentheses">
</div> </div>
<h2 id="do-not-end-markdown-links-with">Do not end markdown links with “<code>))</code>”</h2> <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 <p>Markdown links that end in “<code>))</code>” complicate parsing and sometimes lead
to incorrect URLs or file paths.</p> to incorrect URLs or file paths.</p>
<p><span style="color:red">❌</span> Incorrect</p> <p><span style="color:red">❌</span> Incorrect.</p>
<pre class="&lt;!---markdown--&gt;"><code>[some text](https://example.com/foo_(bar)) <pre><code> [some text](https://example.com/foo_(bar))
This thing, ([some text](some/path)), is NOT ideal.</code></pre> This thing, ([some text](some/path)), is NOT ideal.</code></pre>
<p><span style="color:green">✔</span> Correct</p> <p><span style="color:green">✅</span> Correct.</p>
<pre class="&lt;!---markdown--&gt;"><code>[some text](https://example.com/foo_&amp;lpar;bar&amp;rpar;) <pre><code> [some text](https://example.com/foo_&amp;lpar;bar&amp;rpar;)
This thing, [some text](some/path), is better.</code></pre> This thing, [some text](some/path), is better.</code></pre>
<div id="italics"> <div id="italics">
</div> </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 Instead use an underscore (<code>_</code>). Using an asterisk can complicate
parsing and sometimes lead to incorrect results. This can especially parsing and sometimes lead to incorrect results. This can especially
go for when it is <strong><em>bold and italic</em></strong>.</p> go for when it is <strong><em>bold and italic</em></strong>.</p>
<p><span style="color:red">❌</span> Incorrect</p> <p><span style="color:red">❌</span> Incorrect.</p>
<pre class="&lt;!---markdown--&gt;"><code>*this text is italic* <pre><code> *this text is italic*
***this text is bold italic***</code></pre> ***this text is bold italic***</code></pre>
<p><span style="color:green">✔</span> Correct</p> <p><span style="color:green">✅</span> Correct.</p>
<pre class="&lt;!---markdown--&gt;"><code>_this text is italic_ <pre><code> _this text is italic_
**_this text is bold italic_** **_this text is bold italic_**
_**this text is bold italic**_</code></pre> _**this text is bold italic**_</code></pre>
<p><strong>BTW</strong>: the astute reader might notice that some cases of <code>*</code> for italic <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 might have slipped through. We do ask you, however, to please
observe this rule, as best you can. observe this rule, as best you can.
markdown.md
+271 -195
View File
@@ -1,11 +1,10 @@
# IOCCC 29th Markdown Guidelines # IOCCC 29th Markdown Guidelines
## Markdown Guidelines Version ## 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 ## 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 standards and some of our guidelines help integrate winning entries into
the website more easily. 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)". See the FAQ on "[remarks.md submission file](faq.html#remarks_md)".
Nevertheless, the IOCCC does have certain practices that we ask authors to 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 follow. Some of these relate to use of markdown directly and others relate
to injecting HTML into the markdown file. 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 &#x274c; for the incorrect method
and ✔️ for preferred correct one. and ✔️ for preferred correct one.
<div id="sections"></div> <div id="sections"></div>
## Start `remarks.md` sections at level 3 ## Start `remarks.md` sections at level 3
If (it is not required) you do use sections in your `remarks.md` file (this does 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: 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. <span style="color:red">&#x274c;</span> Reserved in `remarks.md` only.
```<!---markdown--> ``` <!---markdown-->
# Section Reserved # Section Reserved
## Section Reserved ## Section Reserved
``` ```
<span style="color:green">✔</span> Available every where. <span style="color:green">&#x2705;</span> Available every where.
``` ```
### Section Level 3 ### Section Level 3
#### Section Level 4 #### Section Level 4
##### Section Level 5 ##### Section Level 5
###### Section Level 6 ###### Section Level 6
``` ```
<div id="anchor-name"></div> <div id="anchor-name"></div>
## Replace `<a name="anchor_name"></a>` construct.
<span style="color:red">❌</span> Incorrect. ## Replace `<a name="anchor_name"></a>` construct
```<!---html-->
<a name="old_way">Section title</a> <span style="color:red">&#x274c;</span> Incorrect.
``` <!---html-->
<a name="old_way">Section title</a>
``` ```
<span style="color:green">✔</span> Correct. <span style="color:green">&#x2705;</span> Correct.
```<!---html--> ``` <!---html-->
<div id="new_way"></div> <div id="new_way"></div>
### Section title ### Section title
``` ```
<div id="links"></div> <div id="links"></div>
## Markdown links instead of `<a>...</a>` ## Markdown links instead of `<a>...</a>`
<span style="color:red">❌</span> Incorrect. <span style="color:red">&#x274c;</span> Incorrect.
```<!---html--> ``` <!---html-->
This <a href="#link_target>HTML link text</a> works, but we prefer see below... This <a href="#link_target>HTML link text</a> works, but we prefer see below...
``` ```
<span style="color:green">✔</span> Correct. <span style="color:green">&#x2705;</span> Correct.
```<!---html--> ``` <!---html-->
[markdown link text](#link_target) [markdown link text](#link_target)
``` ```
<div id="del"></div><div id="strike"></div> <div id="del"></div><div id="strike"></div>
## Replace `<strike>` or `<s>` ## Replace `<strike>` or `<s>`
<span style="color:red">❌</span> Incorrect. <span style="color:red">&#x274c;</span> Incorrect.
```<!---html--> ``` <!---html-->
<strike>striked through text</strike> <strike>striked through text</strike>
<s>HTML 5 striked through text</s> <s>HTML 5 striked through text</s>
``` ```
<span style="color:green">✔</span> Correct. <span style="color:green">&#x2705;</span> Correct.
```<!---html--> ``` <!---html-->
~~markdown striked through text~~ ~~markdown striked through text~~
<del>HTML 5 striked through text</del> <del>HTML 5 striked through text</del>
``` ```
<div id="ins"></div><div id="underline"></div> <div id="ins"></div><div id="underline"></div>
## Replace `<u>` ## Replace `<u>`
<span style="color:red">❌</span> Incorrect. <span style="color:red">&#x274c;</span> Incorrect.
```<!---html--> ``` <!---html-->
<u>old tags</u> <u>old tags</u>
``` ```
<span style="color:green">✔</span> Correct. <span style="color:green">&#x2705;</span> Correct.
```<!---html--> ``` <!---html-->
<ins>HTML 5 tags</ins> <ins>HTML 5 tags</ins>
``` ```
<div id="tt"></div> <div id="tt"></div>
## Replace `<tt>` ## Replace `<tt>`
<span style="color:red">❌</span> Incorrect. <span style="color:red">&#x274c;</span> Incorrect.
```<!---html--> ``` <!---html-->
<tt>obsolete HTML</tt> <tt>obsolete HTML</tt>
``` ```
<span style="color:green">✔</span> Correct. <span style="color:green">&#x2705;</span> Correct.
```<!---html--> ``` <!---html-->
<span style="font-family: monospace;">monospace font</span> <span style="font-family: monospace;">monospace font</span>
`markdown style monospace` `markdown style monospace`
``` ```
<div id="indent"></div> <div id="indent"></div>
## Indent code blocks by four spaces, not by TAB.
<span style="color:red">❌</span> Incorrect. ## Indent code blocks by four spaces, not by TAB
```<!---sh-->
echo "This code block is NOT indented" <span style="color:red">&#x274c;</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) We request that you indent the code block by multiples of four (4)
ASCII SPACES, never TAB (␉): ASCII SPACES, never TAB (␉):
<span style="color:green">✔</span> Correct. <span style="color:green">&#x2705;</span> Correct.
````<!---sh--> ```` <!---markdown-->
echo "This code block is indented by multiples of 4 spaces" ``` <!---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.
```` ````
Alternatively its possible to use ` ``` ` marks, without the initial If you need to intent more than one level, use multiples of 4 ASCII spaces (no tabs):
four (4) space indentation. This is usually the better method.
<span style="color:green">✔</span> Also correct. <span style="color:green">&#x2705;</span> Also Correct.
````<!---markdown--> ```` <!---markdown-->
``` ``` <!---sh-->
The same thing applies to any markdown block bracketed by ``` lines. 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 (&#x60;&#x60;&#x60;) without the initial
four (4) space indentation, we **prefer** that you multiples of 4 spaces if possible:
<span style="color:green">&#x2705;</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">&#x2705;</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> <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 Please do **NOT** indent with ASCII TABs (␉), **OR** use any ASCII TAB
(␉) anywhere inside a markdown file. (␉) 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) If you need to indent two (2) or more levels, use multiples of four (4)
ASCII SPACES. ASCII SPACES.
<span style="color:red">❌</span> Incorrect for markdown files only. <span style="color:red">&#x274c;</span> Incorrect for markdown files only.
````<!---markdown--> ```` <!---markdown-->
``` ```
␉Please do **NOT**␉use ASCII tabs␉in markdown files. ␉Please do **NOT**␉use ASCII tabs␉in markdown files.
␉␉Please do **NOT** indent markdown with ASCII tabs. ␉␉Please do **NOT** indent markdown with ASCII tabs.
␉We␉don't␉mind␉tabs␉in␉general, ␉We␉don't␉mind␉tabs␉in␉general,
␉We just ask that you NOT use them in markdown files. ␉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. <span style="color:green">&#x2705;</span> OK for all file types, e.g., `.c`, `.h`, `.mk`, `.sh`, **EXCEPT** `.md` markdown files.
````<!---c--> ```` <!---c-->
␉printf("It is fine␉to␉use tabs in Obfuscated C code.\n"); ␉printf("It is fine␉to␉use tabs in Obfuscated C code.\n");
␉␉/*␉if␉you␉wish */ ␉␉/*␉if␉you␉wish */
␉// We ask that you to NOT use ASCII tab characters in your remarks.md writeup, ␉// 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. ␉// 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> <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. 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 <span style="color:red">&#x274c;</span> Incorrect.
````<!---markdown--> ```` <!---markdown-->
```c ```c
int main(void) {return 0;} int main(void) {return 0;}
``` ```
```` ````
Instead, put the language inside an HTML comment, separated from the Instead, put the language inside an HTML comment, separated from the
markdown code block starting fence by a space: markdown code block starting fence by a space:
<span style="color:green">✔</span> Correct <span style="color:green">&#x2705;</span> Correct.
````<!---markdown--> ```` <!---markdown-->
```<!---c--> ``` <!---c-->
int main(void) {return 0;} int main(void) {return 0;}
``` ```
```` ````
**PLEASE NOTE**: There is an **IMPORTANT** ASCII SPACE between the 3 backticks (&#x60;&#x60;&#x60;)
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> <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 (` ``` `). ## Ensure blank line between code block and text
````<!---markdown-->
``` <span style="color:red">&#x274c;</span> Incorrect, missing empty line after closing 3 backtick (&#x60;&#x60;&#x60;) fence.
int ```` <!---markdown-->
main(int foo) ``` <!---c-->
{ /* The C compiler will insist in flagging this an error, unfortunately */
return foo; int
} main(int foo)
``` {
C compilers cannot be given a -Wno-main-arg-errors flag. 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. <span style="color:green">&#x2705;</span> Correct, has empty line between closing fence and subsequent text.
````<!---markdown--> ```` <!---markdown-->
``` ``` <!---c-->
int /* The C compiler will insist in flagging this an error, unfortunately */
main(int foo) int
{ main(int foo)
return 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> <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 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 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). 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 <span style="color:red">&#x274c;</span> Incorrect.
```<!---html--> ``` <!---html-->
<br/> <br/>
<hr/> <hr/>
<img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of <img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of
the 1984 anonymous C code" width=600 height=401 /> the 1984 anonymous C code" width=600 height=401 />
``` ```
<span style="color:green">✔</span> Correct <span style="color:green">&#x2705;</span> Correct.
```<!---html--> ``` <!---html-->
<br> <br>
<hr> <hr>
<img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of <img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of
the 1984 anonymous C code" width=600 height=401> the 1984 anonymous C code" width=600 height=401>
``` ```
<div id="br"></div><div id="backslash"></div> <div id="br"></div><div id="backslash"></div>
## Do not use a trailing backslash outside of a code block ## 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. <span style="color:red">&#x274c;</span> Incorrect, do not use escaped newlines outside of a code block.
```<!---markdown--> ``` <!---markdown-->
In markdown,\ In markdown,\
do NOT use trailing\ do NOT use trailing\
backslashes outside of\ backslashes outside of\
a code block a code block
``` ```
<span style="color:green">✔</span> Correct <span style="color:green">&#x2705;</span> Correct.
````<!---html--> ```` <!---html-->
In markdown,<br> In markdown,<br>
use trailing<br> use trailing<br>
br's outside of<br> br's outside of<br>
a code block a code block
``` ```
This is OK\ This is OK\
inside a\ inside a\
markdown code\ markdown code\
block block
``` ```
`This is OK\` `This is OK\`
```` ````
Doing it this way will prevent `pandoc(1)` from generating deprecated Doing it this way will prevent `pandoc(1)` from generating deprecated
HTML elements, such as `<br />`. HTML elements, such as `<br />`.
<div id="img"></div> <div id="img"></div>
## Do not use markdown style images ## Do not use markdown style images
<span style="color:red">❌</span> Incorrect <span style="color:red">&#x274c;</span> Incorrect.
```<!---markdown--> ``` <!---markdown-->
![alt text](filename.png "Title") ![alt text](filename.png "Title")
``` ```
<span style="color:green">✔</span> Correct <span style="color:green">&#x2705;</span> Correct.
```<!---markdown--> ``` <!---markdown-->
<img src="filename.png" <img src="filename.png"
alt="describe the filename.png image for someone who cannot view it" alt="describe the filename.png image for someone who cannot view it"
width=PIXEL_WIDTH height=PIXEL_HEIGHT> 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 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 and `height` information so browsers have to slow down on rendering
text around the image until it can internally determine the image size. text around the image until it can internally determine the image size.
<div id="hr"></div> <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 Please do **NOT** use `---` style lines in markdown to create horizontal
lines or to separate sections. 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 no effect in standard HTML 5 and interacts badly with unquoted attribute
values. values.
<span style="color:red">❌</span> Incorrect <span style="color:red">&#x274c;</span> Incorrect.
```<!---html--> ``` <!---html-->
* * * * * *
- - - - - -
--- ---
``` ```
<span style="color:green">✔</span> Correct <span style="color:green">&#x2705;</span> Correct.
```<!---html--> ``` <!---html-->
Regular divider... Regular divider...
<hr> <hr>
A short divider... A short divider...
<hr style="width:10%;text-align:left;margin-left:0"> <hr style="width:10%;text-align:left;margin-left:0">
``` ```
<div id="parentheses"></div> <div id="parentheses"></div>
## Do not put a literal "`(`" or "`)`" in markdown link titles ## Do not put a literal "`(`" or "`)`" in markdown link titles
<span style="color:red">❌</span> Incorrect <span style="color:red">&#x274c;</span> Incorrect.
```<!---markdown--> ``` <!---markdown-->
[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)
``` ```
<span style="color:green">✔</span> Correct <span style="color:green">&#x2705;</span> Correct.
```<!---markdown--> ``` <!---markdown-->
[some &lpar;text&rpar;](https://example.com/curds) [some &lpar;text&rpar;](https://example.com/curds)
[ls&lpar;1&rpar;](https://example.com/ls-man-page.1) [ls&lpar;1&rpar;](https://example.com/ls-man-page.1)
``` ```
<div id="closing-parentheses"></div> <div id="closing-parentheses"></div>
## Do not end markdown links with "`))`" ## Do not end markdown links with "`))`"
Markdown links that end in "`))`" complicate parsing and sometimes lead Markdown links that end in "`))`" complicate parsing and sometimes lead
to incorrect URLs or file paths. to incorrect URLs or file paths.
<span style="color:red">❌</span> Incorrect <span style="color:red">&#x274c;</span> Incorrect.
```<!---markdown--> ``` <!---markdown-->
[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.
``` ```
<span style="color:green">✔</span> Correct <span style="color:green">&#x2705;</span> Correct.
```<!---markdown--> ``` <!---markdown-->
[some text](https://example.com/foo_&lpar;bar&rpar;) [some text](https://example.com/foo_&lpar;bar&rpar;)
This thing, [some text](some/path), is better. This thing, [some text](some/path), is better.
``` ```
<div id="italics"></div> <div id="italics"></div>
## Use `_` for italics in markdown ## Use `_` for italics in markdown
Please do **NOT** use `*` (single asterisk) 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 parsing and sometimes lead to incorrect results. This can especially
go for when it is **_bold and italic_**. go for when it is **_bold and italic_**.
<span style="color:red">❌</span> Incorrect <span style="color:red">&#x274c;</span> Incorrect.
```<!---markdown--> ``` <!---markdown-->
*this text is italic* *this text is italic*
***this text is bold italic*** ***this text is bold italic***
``` ```
<span style="color:green">✔</span> Correct <span style="color:green">&#x2705;</span> Correct.
```<!---markdown--> ``` <!---markdown-->
_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**_
``` ```
**BTW**: the astute reader might notice that some cases of `*` for italic **BTW**: the astute reader might notice that some cases of `*` for italic
might have slipped through. We do ask you, however, to please might have slipped through. We do ask you, however, to please
observe this rule, as best you can. observe this rule, as best you can.
sitemap.xml
+2 -2
View File
@@ -16810,11 +16810,11 @@
</url> </url>
<url> <url>
<loc>https://www.ioccc.org/markdown.html</loc> <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>
<url> <url>
<loc>https://www.ioccc.org/markdown.md</loc> <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>
<url> <url>
<loc>https://www.ioccc.org/news.html</loc> <loc>https://www.ioccc.org/news.html</loc>