update markdown guidelines to 29.0 2025-11-26
Changed the markdown guidelines version to "29.0 2025-11-26". Ran `make markdown timestamp` to perform the above.
This commit is contained in:
Landon Curt Noll committed
1 parent
a039928179
commit
9907d445bb
3 files changed
+248
-366
No files matched your search
+240
-358
@@ -452,419 +452,301 @@
|
|||||||
<!-- START: this line starts content for HTML phase 21 by: bin/pandoc-wrapper.sh via bin/md2html.sh -->
|
<!-- START: this line starts content for HTML phase 21 by: bin/pandoc-wrapper.sh via bin/md2html.sh -->
|
||||||
|
|
||||||
<!-- BEFORE: 1st line of markdown file: markdown.md -->
|
<!-- BEFORE: 1st line of markdown file: markdown.md -->
|
||||||
<div id="markdown_guidelines">
|
<h1 id="ioccc-29th-markdown-guidelines">IOCCC 29th Markdown Guidelines</h1>
|
||||||
<h1 id="ioccc-28th-markdown-guidelines">IOCCC 28th Markdown Guidelines</h1>
|
<h2 id="markdown-guidelines-version">Markdown Guidelines Version</h2>
|
||||||
</div>
|
<p>These <a href="markdown.html">Markdown Guidelines</a> are version <strong>29.0 2025-11-26</strong>.</p>
|
||||||
<div id="markdown_version">
|
|
||||||
<h2 id="ioccc-markdown-guidelines-version">IOCCC Markdown guidelines version</h2>
|
|
||||||
</div>
|
|
||||||
<p class="leftbar">
|
|
||||||
These <a href="markdown.html">IOCCC markdown guidelines</a> are version <strong>28.4 2025-04-28</strong>.
|
|
||||||
</p>
|
|
||||||
<p><strong>IMPORTANT</strong>: Be sure to read the <a href="next/rules.html">IOCCC rules</a> and <a href="next/guidelines.html">IOCCC
|
|
||||||
guidelines</a>.</p>
|
|
||||||
<p>Jump to: <a href="#">top</a></p>
|
|
||||||
<div id="introduction">
|
<div id="introduction">
|
||||||
<h2 id="ioccc-markdown-guidelines-introduction">IOCCC Markdown Guidelines Introduction</h2>
|
|
||||||
</div>
|
</div>
|
||||||
<p>The IOCCC makes extensive use of <a href="https://daringfireball.net/projects/markdown/">markdown</a>.
|
<h2 id="introduction">Introduction</h2>
|
||||||
For example, when submitting to the IOCCC
|
<p>The IOCCC makes extensive use of <a href="https://daringfireball.net/projects/markdown/">markdown</a>. For example, when
|
||||||
we have people
|
submitting to the IOCCC we have people submit remarks about their
|
||||||
submit remarks about their entry in markdown format. Every
|
entry in markdown format. Every <a href="years.html">winning entry</a> uses a <code>README.md</code>
|
||||||
<a href="years.html">winning IOCCC entry</a> uses a <code>README.md</code> markdown file
|
markdown file as the basis for forming the <code>index.html</code> web page for
|
||||||
as the basis for forming the <code>index.html</code> web page for that entry.
|
that entry. All HTML 5 generated pages on the <a href="https://www.ioccc.org/index.html">Official IOCCC website</a>
|
||||||
All generated HTML pages on the <a href="https://www.ioccc.org/index.html">Official IOCCC website</a>
|
start with some markdown content. We no longer support older HTML
|
||||||
start with some markdown content.</p>
|
standards and some of our guidelines help integrate winning entries into
|
||||||
<p>See the <a href="https://www.markdownguide.org/basic-syntax">markdown syntax</a> guide.
|
the website more easily.</p>
|
||||||
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
|
See the FAQ on “<a href="faq.html#remarks_md">remarks.md submission file</a>”.</p>
|
||||||
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.
|
follow. Some of these relate to use of markdown directly and others relate
|
||||||
Some of these relate to use of markdown directly and others relate to injecting HTML
|
to injecting HTML into the markdown file.</p>
|
||||||
into the markdown file.</p>
|
<p>In the sections below, examples will mark by ❌ for the incorrect method
|
||||||
<p>Jump to: <a href="#">top</a></p>
|
and ✔️ for preferred correct one.</p>
|
||||||
<div id="sections">
|
<div id="sections">
|
||||||
<h2 id="please-do-start-remarks.md-sections-at-level-3-increasing-for-subsections-up-to-6">Please DO start <code>remarks.md</code> sections at level 3 (<code>###</code>), increasing for subsections up to 6 (<code>######</code>)</h2>
|
|
||||||
</div>
|
</div>
|
||||||
<p>IF (it is not required) you do use sections in your <code>remarks.md</code> file (this does
|
<h2 id="start-remarks.md-sections-at-level-3">Start <code>remarks.md</code> sections at level 3</h2>
|
||||||
not apply to other markdown files), <strong>PLEASE</strong> start at level three:</p>
|
<p>If (it is not required) you do use sections in your <code>remarks.md</code> file (this does
|
||||||
<pre><code> # Foo <=== no thank you
|
not apply to other markdown files), <strong>PLEASE</strong> start at level three up to level six:</p>
|
||||||
## Foo <=== no thank you</code></pre>
|
<pre class="<!---markdown-->"><code>❌ # Section Reserved
|
||||||
<p>Instead, start sections with 3 <code>#</code>s:</p>
|
❌ ## Section Reserved
|
||||||
<pre><code> ### Section 0</code></pre>
|
✔️ ### Section Level 3
|
||||||
<p>For each subsection of the current section, add another <code>#</code>, up to 6, going back
|
✔️ #### Section Level 4
|
||||||
to 3 for new sections. For instance:</p>
|
✔️ ##### Section Level 5
|
||||||
<pre><code> ### Section 0
|
✔️ ###### Section Level 6</code></pre>
|
||||||
...
|
|
||||||
#### 1st subsection of section 0
|
|
||||||
...
|
|
||||||
##### 1st sub-subsection of the 1st subsection of section 0
|
|
||||||
...
|
|
||||||
#### 2nd subsection of section 0
|
|
||||||
...
|
|
||||||
##### 1st sub-subsection of the 2nd subsection of section 0
|
|
||||||
...
|
|
||||||
##### 2nd sub-subsection of the 2nd subsection of section 0
|
|
||||||
...
|
|
||||||
###### 1st sub-sub-subsection of the 2nd sub-subsection of the 2nd subsection of section 0
|
|
||||||
...
|
|
||||||
### Section 1
|
|
||||||
...
|
|
||||||
### Section 2
|
|
||||||
...
|
|
||||||
Etc.</code></pre>
|
|
||||||
<div id="name">
|
|
||||||
<div id="anchor-name">
|
<div id="anchor-name">
|
||||||
<h2 id="please-do-not-use-the-name-attributes-in-html-a...a-hyperlink-elements">Please do NOT use the <code>name</code> attributes in HTML <code><a>...</a></code> hyperlink elements</h2>
|
|
||||||
</div>
|
</div>
|
||||||
</div>
|
<h2 id="replace-a-nameanchor_namea-construct.">Replace <code><a name="anchor_name"></a></code> construct.</h2>
|
||||||
<p>Please do <strong>NOT</strong> use the HTML construct:</p>
|
<pre class="<!---html-->"><code>❌ <a name="old_way">...</a>
|
||||||
<pre><code> <a name="string">...</a> <=== no thank you</code></pre>
|
✔️ <span id="new_way">...</span></code></pre>
|
||||||
<p>as those are <strong>NOT</strong> part of the HTML 5 standard.</p>
|
|
||||||
<p>Instead use:</p>
|
|
||||||
<pre><code> <div id="string">...</div></code></pre>
|
|
||||||
<p>where the <code>...</code> is the HTML you want to “name”. The <code><div></code>
|
|
||||||
encapsulates the HTML you want to name: i.e., the target of some
|
|
||||||
<code><a href="#string"></code> or some other <code><a href="URL#string"></code>
|
|
||||||
for the given page URL.</p>
|
|
||||||
<h3 id="important-point">IMPORTANT POINT:</h3>
|
|
||||||
<p>There are certain markdown constructs that <strong>CANNOT</strong> have an <strong>internal</strong> <code><div id="string">...</div></code> element.</p>
|
|
||||||
<p>An example is headings (lines that start with a <code>#</code>). For example:</p>
|
|
||||||
<pre><code> # <div id="string">THIS WILL NOT WORK!</div> <=== this will not work</code></pre>
|
|
||||||
<p>For things like headings, you have to surround them with the <code><div id="string">...</div></code> element, as in:</p>
|
|
||||||
<pre><code> <div id="string">
|
|
||||||
# This will work
|
|
||||||
</div></code></pre>
|
|
||||||
<p>While some browsers will still recognize the HTML construct <code><a name="string">...</a></code>, it is possible <strong>they MIGHT NOT</strong> in the future.</p>
|
|
||||||
<p>Jump to: <a href="#">top</a></p>
|
|
||||||
<div id="links">
|
<div id="links">
|
||||||
<h2 id="if-you-can-it-is-preferable-to-use-markdown-links-rather-than-a...a">If you can, it is PREFERABLE to use markdown links rather than <code><a>...</a></code></h2>
|
|
||||||
</div>
|
</div>
|
||||||
<p>It is easier and preferred to use markdown links rather than HTML <code><a>..</a></code>
|
<h2 id="markdown-links-instead-of-a...a">Markdown links instead of <code><a>...</a></code></h2>
|
||||||
anchors.</p>
|
<pre class="<!---html-->"><code>❌ This <a href="#link_target>HTML link text</a> works, but we prefer
|
||||||
<p>Instead of:</p>
|
✔️ [markdown link text](#link_target)</code></pre>
|
||||||
<pre><code> Use of <a href="#links>HTML anchors</a>
|
|
||||||
is one option, however ...</code></pre>
|
|
||||||
<pre><code> [markdown links](#links) are easier and preferred</code></pre>
|
|
||||||
<p>Jump to: <a href="#">top</a></p>
|
|
||||||
<div id="strike">
|
|
||||||
<div id="del">
|
<div id="del">
|
||||||
<h2 id="please-do-not-use-the-strike-or-the-s-html-element">Please do NOT use the <code><strike></code> or the <code><s></code> HTML element</h2>
|
|
||||||
</div>
|
</div>
|
||||||
|
<div id="strike">
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
<p>Please do <strong>NOT</strong> use the obsolete <code><strike></code> or the obsolete <code><s></code>
|
<h2 id="replace-strike-or-s">Replace <code><strike></code> or <code><s></code></h2>
|
||||||
(<del><strong>strikeout</strong></del>) HTML elements:</p>
|
<pre class="<!---html-->"><code>❌ <strike>striked through text</strike>
|
||||||
<pre><code> <strike>...</strike> <=== no thank you
|
❌ <s>HTML 5 striked through text</s>
|
||||||
<s>...</s> <=== no thank you</code></pre>
|
|
||||||
<p>Use instead:</p>
|
✔️ <del>HTML 5 striked through text</del>
|
||||||
<pre><code> <del>...</del></code></pre>
|
✔️ ~~markdown striked through text~~</code></pre>
|
||||||
<p>Jump to: <a href="#">top</a></p>
|
|
||||||
<div id="underline">
|
|
||||||
<div id="ins">
|
<div id="ins">
|
||||||
<h2 id="please-do-not-use-the-u-html-element">Please do NOT use the <code><u></code> HTML element</h2>
|
|
||||||
</div>
|
</div>
|
||||||
|
<div id="underline">
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
<p>Please do <strong>NOT</strong> use the obsolete <code><u></code> (<ins><em>underline</em></ins>) HTML element:</p>
|
<h2 id="replace-u">Replace <code><u></code></h2>
|
||||||
<pre><code> <u>...</u> <=== no thank you</code></pre>
|
<pre class="<!---html-->"><code>❌ <u>old tags</u>
|
||||||
<p>Use instead:</p>
|
✔️ <ins>HTML 5 tags</ins></code></pre>
|
||||||
<pre><code> <ins>...</ins></code></pre>
|
|
||||||
<p>Jump to: <a href="#">top</a></p>
|
|
||||||
<div id="tt">
|
<div id="tt">
|
||||||
<div id="span">
|
|
||||||
<h2 id="please-do-not-use-the-tt-html-element">Please do NOT use the <code><tt></code> HTML element</h2>
|
|
||||||
</div>
|
|
||||||
</div>
|
|
||||||
<p>Please do <strong>NOT</strong> use the obsolete <code><tt></code>
|
|
||||||
(<span style="font-family: monospace;"><strong>teletype</strong></span>) HTML element:</p>
|
|
||||||
<pre><code> <tt>The tt element is obsolete</tt> <=== no thank you</code></pre>
|
|
||||||
<p>Instead use either a monospaced <code><span></code> or an inline markdown code block:</p>
|
|
||||||
<pre><code> <span style="font-family: monospace;">Use of a monospaced font
|
|
||||||
is one option,
|
|
||||||
however ... </span></code></pre>
|
|
||||||
<p>We recommend using the inline markdown code block method instead:</p>
|
|
||||||
<pre><code> Using the `inline markdown code block` is easier and is **preferred**.</code></pre>
|
|
||||||
<p>Jump to: <a href="#">top</a></p>
|
|
||||||
<div id="unindented">
|
|
||||||
<div id="indented">
|
|
||||||
<h2 id="please-do-not-use-unindented-code-blocks">Please do NOT use unindented code blocks</h2>
|
|
||||||
</div>
|
|
||||||
</div>
|
|
||||||
<p>Please do <strong>NOT</strong> start code blocks at the first column.</p>
|
|
||||||
<p>For example:</p>
|
|
||||||
<pre class="<!---markdown-->"><code>``` <!---sh-->
|
|
||||||
echo "This code block is NOT indented" <=== no thank you
|
|
||||||
```</code></pre>
|
|
||||||
<p>We request that you indent the code block by multiples of 4 ASCII <strong>SPACES</strong>:</p>
|
|
||||||
<pre class="<!---markdown-->"><code>``` <!---sh-->
|
|
||||||
echo "This code block is indented by mutiples of 4 spaces"
|
|
||||||
|
|
||||||
# The top level starts with a 4 ASCII space indent.
|
</div>
|
||||||
#
|
<h2 id="replace-tt">Replace <code><tt></code></h2>
|
||||||
# Only indent with multiples of 4 ASCII spaces.
|
<pre class="<!---html-->"><code>❌ <tt>obsolete HTML</tt>
|
||||||
# 2nd level indent needs 8 ASCII spaces (no tabs).
|
✔️ <span style="font-family: monospace;">monospace font</span>
|
||||||
# 3rd level indent needs 12 ASCII spaces (no tabs).
|
✔️ `markdown style monospace`</code></pre>
|
||||||
# etc.
|
<div id="indent">
|
||||||
```</code></pre>
|
|
||||||
<p>Moreover:</p>
|
</div>
|
||||||
<pre class="<!---markdown-->"><code>```
|
<h2 id="indent-code-blocks-by-four-spaces-not-by-tab.">Indent code blocks by four spaces, not by TAB.</h2>
|
||||||
The same thing applies to any markdown block surrounded by ``` lines.
|
<pre class="<!---sh-->"><code>❌ echo "This code block is NOT indented"</code></pre>
|
||||||
```</code></pre>
|
<p>We request that you indent the code block by multiples of four (4)
|
||||||
<p>Please do <strong>NOT</strong> indent using ASCII tab characters in markdown files.</p>
|
ASCII SPACES, never TAB (␉):</p>
|
||||||
<p>Jump to: <a href="#">top</a></p>
|
<pre class="<!---sh-->"><code>✔️ 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.</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>
|
||||||
|
<pre class="<!---markdown-->"><code>✔️ ```
|
||||||
|
✔️ The same thing applies to any markdown block bracketed by ``` lines.
|
||||||
|
✔️ ```</code></pre>
|
||||||
<div id="tabs">
|
<div id="tabs">
|
||||||
|
|
||||||
|
</div>
|
||||||
<div id="spaces">
|
<div id="spaces">
|
||||||
<h2 id="please-do-not-use-ascii-tabs-in-markdown-files">Please do NOT use ASCII tabs in markdown files</h2>
|
|
||||||
</div>
|
</div>
|
||||||
</div>
|
<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
|
<p>Please do <strong>NOT</strong> indent with ASCII TABs (␉), <strong>OR</strong> use any ASCII TAB
|
||||||
ASCII tab characters 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,
|
||||||
we have discovered that ASCII tab characters create problems when
|
we have discovered that ASCII TAB (␉) characters create problems when
|
||||||
used as part of the leading whitespace within a markdown file.</p>
|
used as part of the leading whitespace within a markdown file.</p>
|
||||||
<p>If you need to indent 2 or more levels, use multiples of 4 ASCII
|
<p>If you need to indent two (2) or more levels, use multiples of four (4)
|
||||||
<strong>SPACES</strong>.</p>
|
ASCII SPACES.</p>
|
||||||
<p>For example:</p>
|
|
||||||
<pre class="<!---markdown-->"><code>```
|
<pre class="<!---markdown-->"><code>```
|
||||||
Please do **NOT** use ASCII tabs in markdown files. <=== no thank you
|
❌ ␉Please do **NOT**␉use ASCII tabs␉in markdown files.
|
||||||
Please do **NOT** indent markdown with ASCII tabs. <=== no thank you
|
❌ ␉␉Please do **NOT** indent markdown with ASCII tabs.
|
||||||
|
|
||||||
We don't mind tabs in general, <=== no thank you
|
❌ ␉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.
|
||||||
```</code></pre>
|
```</code></pre>
|
||||||
<p>And to clarify, we are only talking about markdown files,
|
<p>And to clarify, we are only talking about markdown files, not C code or
|
||||||
not C code or any other non-markdown content:</p>
|
any other non-markdown content:</p>
|
||||||
<pre class="<!---c-->"><code> printf("It is fine to use tabs in Obfuscated C code.\n");
|
<pre class="<!---c-->"><code>✔️ 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.</code></pre>
|
✔️ // or in any other markdown files within your entry, please.</code></pre>
|
||||||
<p><strong>NOTE</strong>: Again, you are <strong>perfectly welcome</strong> to use ASCII tab characters in
|
<p><strong>NOTE</strong>: Again, you are <strong>perfectly welcome</strong> to use ASCII tab characters
|
||||||
your C code and other non-markdown files. We simply ask that you do <strong>NOT</strong> use any
|
in your C code and other non-markdown files. We simply ask that
|
||||||
ASCII tab characters in markdown files.</p>
|
you do <strong>NOT</strong> use any ASCII TAB (␉) characters in markdown files.</p>
|
||||||
<p>Jump to: <a href="#">top</a></p>
|
|
||||||
<div id="vim-tabs">
|
|
||||||
<h3 id="tip-for-vim-users">Tip for <code>vim</code> users</h3>
|
|
||||||
</div>
|
|
||||||
<p>If you use <code>vim</code> you can put in your <code>.vimrc</code> file (usually <code>~/.vimrc</code>) the
|
|
||||||
following settings to make sure the tabs are not put in without you noticing:</p>
|
|
||||||
<pre><code> set tabstop=8 " a tab is 8 spaces (or whatever you wish it to be set to)
|
|
||||||
set softtabstop=4 " ...but when inserting/backspacing use 4 spaces
|
|
||||||
set shiftwidth=4 " ...and auto-indent 4 spaces (when autoindent is set)
|
|
||||||
set expandtab " ...expand tab into spaces</code></pre>
|
|
||||||
<p>If you have file type detection enabled you can, if you prefer, have these
|
|
||||||
settings set just for markdown files:</p>
|
|
||||||
<pre><code> autocmd! Filetype markdown setlocal set tabstop=8 softtabstop=4 shiftwidth=4 expandtab</code></pre>
|
|
||||||
<p>or so.</p>
|
|
||||||
<p>This will prevent the tab key from inserting tabs; rather it will insert 4
|
|
||||||
spaces.</p>
|
|
||||||
<p>To <strong>VERIFY</strong> that there are no tabs in a file you may do, in command mode:</p>
|
|
||||||
<pre><code> /\t</code></pre>
|
|
||||||
<p>If you’re in insert mode hit <code>ESC</code> first.</p>
|
|
||||||
<p>Jump to: <a href="#">top</a></p>
|
|
||||||
<div id="languages">
|
|
||||||
<div id="code">
|
<div id="code">
|
||||||
<h2 id="please-use-html-comments-to-specify-a-language-for-a-code-block">Please use HTML comments to specify a language for a code block</h2>
|
|
||||||
</div>
|
</div>
|
||||||
|
<div id="languages">
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
<p>We request that <a href="https://www.markdownguide.org/extended-syntax/#fenced-code-blocks">fenced markdown code
|
<h2 id="use-html-comments-for-code-block-language-syntax.">Use HTML comments for code block language syntax.</h2>
|
||||||
blocks</a>
|
<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>
|
<strong>NOT</strong> specify a language directly.</p>
|
||||||
<p>For example:</p>
|
<pre class="<!---markdown-->"><code>❌ ```c
|
||||||
<pre class="<!---markdown-->"><code>```c <=== no thank you
|
❌ 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>
|
||||||
<pre class="<!---markdown-->"><code>``` <!---c-->
|
<pre class="<!---markdown-->"><code>✔️ ```<!---c-->
|
||||||
int main(void) {return 0;}
|
✔️ int main(void) {return 0;}
|
||||||
```</code></pre>
|
✔️ ```</code></pre>
|
||||||
<p><strong>IMPORTANT</strong>: The <strong>initial</strong> <strong>` ` `</strong> must be followed by an <strong>ASCII SPACE</strong>,
|
<p><strong>IMPORTANT</strong>: The <strong>initial</strong> <strong>` ` `</strong> must be
|
||||||
and <strong>THEN</strong> an <strong>opening</strong> <strong><code><!---</code></strong> (a “<code><</code>”, a “<code>!</code>” and then three “<code>-</code>”s), and
|
followed by an <strong>ASCII SPACE</strong>, and <strong>THEN</strong> an <strong>opening</strong> <strong>
|
||||||
<strong>THEN</strong> the <strong>language</strong> and <strong>FINALLY</strong> a <strong>closing</strong> “<code>--></code>” (two “<code>-</code>”s
|
<code><!---</code></strong> (a “<code><</code>”, a “<code>!</code>” and then three “<code>-</code>”s), and <strong>THEN</strong>
|
||||||
|
the <strong>language</strong> and <strong>FINALLY</strong> a <strong>closing</strong> “<code>--></code>” (two “<code>-</code>”s
|
||||||
followed by a “<code>></code>”).</p>
|
followed by a “<code>></code>”).</p>
|
||||||
<p>Jump to: <a href="#">top</a></p>
|
<div id="code-and-text">
|
||||||
<div id="slash">
|
|
||||||
<div id="void">
|
|
||||||
<h2 id="please-do-not-add-trailing-slash-to-void-html-elements">Please do NOT add trailing slash to void HTML elements</h2>
|
|
||||||
</div>
|
</div>
|
||||||
|
<h2 id="ensure-blank-line-between-code-block-and-text.">Ensure blank line between code block and text.</h2>
|
||||||
|
<p>Please do <strong>NOT</strong> place text on the next line after a markdown code
|
||||||
|
block. Instead, place a blank line after the end of a markdown code
|
||||||
|
block as this makes it easier to detect when markdown code blocks are
|
||||||
|
<strong>NOT</strong> properly indented.</p>
|
||||||
|
<pre class="<!---markdown-->"><code> ```
|
||||||
|
int
|
||||||
|
main(int foo)
|
||||||
|
{
|
||||||
|
return foo;
|
||||||
|
}
|
||||||
|
❌ ```
|
||||||
|
❌ C compilers cannot be given a -Wno-main-arg-errors flag.
|
||||||
|
|
||||||
|
```
|
||||||
|
int
|
||||||
|
main(int foo)
|
||||||
|
{
|
||||||
|
return foo;
|
||||||
|
}
|
||||||
|
✔️ ```
|
||||||
|
✔️
|
||||||
|
✔️ C compilers cannot be given a -Wno-main-arg-errors flag.</code></pre>
|
||||||
|
<div id="tag-slash">
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
<p>Please do <strong>NOT</strong> use a trailing slash on <a href="https://github.com/validator/validator/wiki/Markup-»-Void-elements">void HTML
|
<h2 id="do-not-add-trailing-slash-to-void-html-tags.">Do not add trailing slash to void HTML tags.</h2>
|
||||||
elements</a>.</p>
|
<p>Please do <strong>NOT</strong> use a trailing slash on
|
||||||
<p>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
|
<a href="https://github.com/validator/validator/wiki/Markup-»-Void-elements">void HTML elements</a>.</p>
|
||||||
tags</a>.</p>
|
<p>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>The trailing slash on void HTML elements has no effect and interacts badly with
|
<p>The trailing slash on void HTML elements has no effect and interacts
|
||||||
unquoted attribute values.</p>
|
badly with unquoted attribute values.</p>
|
||||||
<p>For example, please do <strong>NOT</strong> use markdown like these:</p>
|
<pre class="<!---html-->"><code>❌ <br/>
|
||||||
<pre><code> <br/> <=== no thank you
|
❌ <hr/>
|
||||||
|
❌ <img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of
|
||||||
|
the 1984 anonymous C code" width=600 height=401 />
|
||||||
|
|
||||||
<hr/> <=== no thank you
|
✔️ <br>
|
||||||
|
✔️ <hr>
|
||||||
<img src="1984-anonymous-tattoo.jpg"
|
✔️ <img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of
|
||||||
alt="image of a tattoo of the 1984 anonymous C code"
|
the 1984 anonymous C code" width=600 height=401></code></pre>
|
||||||
width=600 height=401 /> <=== no thank you</code></pre>
|
|
||||||
<p>Instead use, respectively:</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>Jump to: <a href="#">top</a></p>
|
|
||||||
<div id="backslash">
|
|
||||||
<div id="br">
|
<div id="br">
|
||||||
<h2 id="please-do-not-use-a-trailing-backslash-outside-of-a-code-block">Please do NOT use a TRAILING backslash (<code>\</code>) outside of a code block</h2>
|
|
||||||
</div>
|
</div>
|
||||||
|
<div id="backslash">
|
||||||
|
|
||||||
</div>
|
</div>
|
||||||
<p>Unless the line is inside a markdown code block, please do <strong>NOT</strong>
|
<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>
|
||||||
end a markdown line with a trailing backslash (<code>\</code>). Instead use
|
<p>Unless the line is inside a markdown code block, please do <strong>NOT</strong> end
|
||||||
a trailing <code><br></code>.</p>
|
a markdown line with a trailing backslash (<code>\</code>). Instead use a trailing
|
||||||
<p>Instead of:</p>
|
<code><br></code>.</p>
|
||||||
<pre><code> In markdown,\ <=== no thank you
|
<pre class="<!---markdown-->"><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
|
||||||
<p>use:</p>
|
|
||||||
<pre><code> 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</code></pre>
|
✔️ a code block
|
||||||
<p>Again, use of a trailing backslash (<code>\</code>) inside a markdown code block is fine:</p>
|
|
||||||
<pre class="<!---markdown-->"><code>```
|
✔️ ```
|
||||||
This is OK\
|
✔️ This is OK\
|
||||||
inside a\
|
✔️ inside a\
|
||||||
markdown code\
|
✔️ markdown code\
|
||||||
block
|
✔️ block
|
||||||
```</code></pre>
|
✔️ ```
|
||||||
<p>as is:</p>
|
|
||||||
<pre><code> `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
|
<p>Doing it this way will prevent <code>pandoc(1)</code> from generating deprecated
|
||||||
elements such as <code><br /></code>.</p>
|
HTML elements such as <code><br /></code>.</p>
|
||||||
<p>Jump to: <a href="#">top</a></p>
|
|
||||||
<div id="images">
|
|
||||||
<div id="img">
|
<div id="img">
|
||||||
<h2 id="please-do-not-use-markdown-style-images">Please do NOT use markdown style images</h2>
|
|
||||||
</div>
|
</div>
|
||||||
</div>
|
<h2 id="do-not-use-markdown-style-images">Do not use markdown style images</h2>
|
||||||
<p>Please do <strong>NOT</strong> use the markdown embedded image element.</p>
|
|
||||||
<p>Instead of using this markdown element to embed an image:</p>
|
<p>Instead of using this markdown element to embed an image:</p>
|
||||||
<pre><code>  <=== no thank you</code></pre>
|
<pre class="<!---markdown-->"><code>❌ 
|
||||||
<p>Use an <code><img></code> HTML element with <code>alt=</code>, <code>width=</code> and <code>length=</code>
|
|
||||||
attributes:</p>
|
✔️ <img src="filename.png"
|
||||||
<pre><code> <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></code></pre>
|
width=PIXEL_WIDTH height=PIXEL_HEIGHT>
|
||||||
<p>For example, instead of:</p>
|
|
||||||
<pre><code>  <=== no thank you</code></pre>
|
Which allows for HTML <img> attributes `alt=`, `width=` and `length=`.</code></pre>
|
||||||
<p>use this HTML:</p>
|
<p>The problem is that <code>pandoc(1)</code> generates problematic HTML from the
|
||||||
<pre><code> <img src="1984-anonymous-tattoo.jpg"
|
markdown image construct, the resulting HTML does <strong>NOT</strong> have <code>width</code>
|
||||||
alt="image of a tattoo of the 1984 anonymous C code"
|
and <code>height</code> information so browsers have to slow down on rendering
|
||||||
width=600 height=401></code></pre>
|
text around the image until it can internally determine the image size.</p>
|
||||||
<p>The problem goes beyond the fact 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 text around the image until it can internally determine
|
|
||||||
the image size.</p>
|
|
||||||
<p>Jump to: <a href="#">top</a></p>
|
|
||||||
<div id="hr">
|
<div id="hr">
|
||||||
<div id="horizontal">
|
|
||||||
<div id="lines">
|
|
||||||
<h2 id="please-do-not-use-markdown-style-horizontal-lines">Please do NOT use markdown style horizontal lines</h2>
|
|
||||||
</div>
|
|
||||||
</div>
|
|
||||||
</div>
|
</div>
|
||||||
|
<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 a
|
<p>Unless something is inside a markdown <strong>code block</strong>, do <strong>NOT</strong> start
|
||||||
line with 3 or more dashes (“<code>-</code>”s).</p>
|
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
|
<p>Such markdown causes <code>pandoc(1)</code> to generate <code><hr /></code>. The <code><hr /></code> has
|
||||||
effect in standard HTML 5 and interacts badly with unquoted attribute values.</p>
|
no effect in standard HTML 5 and interacts badly with unquoted attribute
|
||||||
|
values.</p>
|
||||||
<p>If a horizontal line is really needed, use:</p>
|
<p>If a horizontal line is really needed, use:</p>
|
||||||
<pre><code> <hr></code></pre>
|
<pre class="<!---html-->"><code>❌ * * *
|
||||||
<p>If a short line is needed, use:</p>
|
❌ - - -
|
||||||
<pre><code> <hr style="width:10%;text-align:left;margin-left:0"></code></pre>
|
❌ ---
|
||||||
<p>Jump to: <a href="#">top</a></p>
|
|
||||||
|
Regular divider...
|
||||||
|
✔️ <hr>
|
||||||
|
|
||||||
|
A short divider...
|
||||||
|
✔️ <hr style="width:10%;text-align:left;margin-left:0"></code></pre>
|
||||||
<div id="parentheses">
|
<div id="parentheses">
|
||||||
<h2 id="please-do-not-put-a-literal-or-in-markdown-link-titles">Please do NOT put a LITERAL “<code>(</code>” or “<code>)</code>” in markdown link titles</h2>
|
|
||||||
</div>
|
</div>
|
||||||
<p>Please do <strong>NOT</strong> use literal parentheses inside markdown link titles.</p>
|
<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>Instead of:</p>
|
<pre class="<!---markdown-->"><code>❌ [some (text)](https://example.com/curds)
|
||||||
<pre><code> [some (text)](https://example.com/curds) <=== no thank you</code></pre>
|
✔️ [some &lpar;text&rpar;](https://example.com/curds)
|
||||||
<p>use:</p>
|
|
||||||
<pre><code> [some &lpar;text&rpar;](https://example.com/curds)</code></pre>
|
❌ [ls(1)](https://example.com/ls-man-page.1)
|
||||||
<p>Instead of:</p>
|
✔️ [ls&lpar;1&rpar;](https://example.com/ls-man-page.1)</code></pre>
|
||||||
<pre><code> [ls(1)](https://example.com/ls-man-page.1) <=== no thank you</code></pre>
|
|
||||||
<p>use:</p>
|
|
||||||
<pre><code> [ls&lpar;1&rpar;](https://example.com/ls-man-page.1)</code></pre>
|
|
||||||
<p>Jump to: <a href="#">top</a></p>
|
|
||||||
<div id="closing-parentheses">
|
<div id="closing-parentheses">
|
||||||
<h2 id="please-do-not-end-markdown-links-with">Please do NOT end markdown links with “<code>))</code>”</h2>
|
|
||||||
</div>
|
</div>
|
||||||
<p>Please do <strong>NOT</strong> end a markdown link with a double closed parenthesis “<code>))</code>”.</p>
|
<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>Instead of:</p>
|
<pre class="<!---markdown-->"><code>❌ [some text](https://example.com/foo_(bar))
|
||||||
<pre><code> [some text](https://example.com/foo_(bar)) <=== no thank you</code></pre>
|
✔️ [some text](https://example.com/foo_&lpar;bar&rpar;)
|
||||||
<p>use:</p>
|
|
||||||
<pre><code> [some text](https://example.com/foo_&lpar;bar&rpar;)</code></pre>
|
|
||||||
<p>As another example, instead of:</p>
|
|
||||||
<pre><code> This thing, ([some text](some/path)), is NOT ideal. <=== no thank you</code></pre>
|
|
||||||
<p>use:</p>
|
|
||||||
<pre><code> This thing, [some text](some/path), is better.</code></pre>
|
|
||||||
<p>Jump to: <a href="#">top</a></p>
|
|
||||||
<div id="code-text">
|
|
||||||
<div id="code-and-text">
|
|
||||||
<div id="text">
|
|
||||||
<h2 id="please-do-not-place-text-on-the-immediate-very-next-line-after-a-markdown-code-block">Please do NOT place text on the IMMEDIATE (very next) line after a markdown code block</h2>
|
|
||||||
</div>
|
|
||||||
</div>
|
|
||||||
</div>
|
|
||||||
<p>Please do <strong>NOT</strong> place text on the next line after a markdown code block.
|
|
||||||
Instead, place a blank line after the end of a markdown code block
|
|
||||||
as this makes it easier to detect when markdown code blocks are
|
|
||||||
<strong>NOT</strong> properly indented.</p>
|
|
||||||
<p>Instead of:</p>
|
|
||||||
<pre class="<!---markdown-->"><code>```
|
|
||||||
int
|
|
||||||
main(int foo)
|
|
||||||
{
|
|
||||||
return foo;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
C compilers cannot be given a -Wno-main-arg-errors flag. <=== no thank you</code></pre>
|
|
||||||
<p>use:</p>
|
|
||||||
<pre class="<!---markdown-->"><code>```
|
|
||||||
int
|
|
||||||
main(int foo)
|
|
||||||
{
|
|
||||||
return foo;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
C compilers cannot be given a -Wno-main-arg-errors flag.</code></pre>
|
❌ This thing, ([some text](some/path)), is NOT ideal.
|
||||||
<p><strong>BTW</strong>: Please note the blank line after the code block.</p>
|
✔️ This thing, [some text](some/path), is better.</code></pre>
|
||||||
<p>Jump to: <a href="#">top</a></p>
|
|
||||||
<div id="italics">
|
<div id="italics">
|
||||||
<h2 id="please-use-_-for-italics-in-markdown">Please use <code>_</code> for italics in markdown</h2>
|
|
||||||
</div>
|
</div>
|
||||||
<p>Please do <strong>NOT</strong> use <code>*</code> (single asterisk) for italics in markdown. Instead use
|
<h2 id="use-_-for-italics-in-markdown">Use <code>_</code> for italics in markdown</h2>
|
||||||
an underscore (<code>_</code>). Using an asterisk can complicate parsing and sometimes lead
|
<p>Please do <strong>NOT</strong> use <code>*</code> (single asterisk) for italics in markdown.
|
||||||
to incorrect results. This can especially go for when it is <strong><em>bold and
|
Instead use an underscore (<code>_</code>). Using an asterisk can complicate
|
||||||
italic</em></strong>.</p>
|
parsing and sometimes lead to incorrect results. This can especially
|
||||||
<p>For example, instead of:</p>
|
go for when it is <strong><em>bold and italic</em></strong>.</p>
|
||||||
<pre><code> *this text is italic* <=== no thank you</code></pre>
|
<pre class="<!---markdown-->"><code>❌ *this text is italic*
|
||||||
<p>use:</p>
|
✔️ _this text is italic_
|
||||||
<pre><code> _this text is italic_</code></pre>
|
|
||||||
<p>Another example, for <strong><em>bold italic</em></strong>:</p>
|
❌ ***this text is bold italic***
|
||||||
<p>Do <strong>NOT</strong> use:</p>
|
✔️ **_this text is bold italic_**
|
||||||
<pre><code> ***this text is bold italic*** <=== no thank you</code></pre>
|
✔️ _**this text is bold italic**_</code></pre>
|
||||||
<p>Instead use:</p>
|
<p><strong>BTW</strong>: the astute reader might notice that some cases of <code>*</code> for
|
||||||
<pre><code> **_this text is bold italic_**</code></pre>
|
italic might have slipped through. We do ask you, however, to please
|
||||||
<p>or:</p>
|
observe this rule, as best you can.
|
||||||
<pre><code> _**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.
|
|
||||||
<!-- AFTER: last line of markdown file: markdown.md --></p>
|
<!-- AFTER: last line of markdown file: markdown.md --></p>
|
||||||
|
|
||||||
<!-- END: this line ends content for HTML phase 21 by: bin/pandoc-wrapper.sh via bin/md2html.sh -->
|
<!-- END: this line ends content for HTML phase 21 by: bin/pandoc-wrapper.sh via bin/md2html.sh -->
|
||||||
|
|||||||
+1
-1
@@ -3,7 +3,7 @@
|
|||||||
|
|
||||||
## Markdown Guidelines Version
|
## Markdown Guidelines Version
|
||||||
|
|
||||||
These [Markdown Guidelines](markdown.html) are version **28.4 2025-04-28**.
|
These [Markdown Guidelines](markdown.html) are version **29.0 2025-11-26**.
|
||||||
|
|
||||||
<div id="introduction"></div>
|
<div id="introduction"></div>
|
||||||
|
|
||||||
|
|||||||
+7
-7
@@ -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-07-26T18:35:07+00:00</lastmod>
|
<lastmod>2025-11-27T07:21:50+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-07-12T17:16:31+00:00</lastmod>
|
<lastmod>2025-11-27T07:21:43+00:00</lastmod>
|
||||||
</url>
|
</url>
|
||||||
<url>
|
<url>
|
||||||
<loc>https://www.ioccc.org/news.html</loc>
|
<loc>https://www.ioccc.org/news.html</loc>
|
||||||
@@ -16826,11 +16826,11 @@
|
|||||||
</url>
|
</url>
|
||||||
<url>
|
<url>
|
||||||
<loc>https://www.ioccc.org/next/guidelines.html</loc>
|
<loc>https://www.ioccc.org/next/guidelines.html</loc>
|
||||||
<lastmod>2025-11-24T13:29:41+00:00</lastmod>
|
<lastmod>2025-11-27T07:11:14+00:00</lastmod>
|
||||||
</url>
|
</url>
|
||||||
<url>
|
<url>
|
||||||
<loc>https://www.ioccc.org/next/guidelines.md</loc>
|
<loc>https://www.ioccc.org/next/guidelines.md</loc>
|
||||||
<lastmod>2025-11-24T13:29:41+00:00</lastmod>
|
<lastmod>2025-11-27T07:11:14+00:00</lastmod>
|
||||||
</url>
|
</url>
|
||||||
<url>
|
<url>
|
||||||
<loc>https://www.ioccc.org/next/index.html</loc>
|
<loc>https://www.ioccc.org/next/index.html</loc>
|
||||||
@@ -16870,11 +16870,11 @@
|
|||||||
</url>
|
</url>
|
||||||
<url>
|
<url>
|
||||||
<loc>https://www.ioccc.org/next/rules.html</loc>
|
<loc>https://www.ioccc.org/next/rules.html</loc>
|
||||||
<lastmod>2025-11-24T13:29:41+00:00</lastmod>
|
<lastmod>2025-11-27T07:11:14+00:00</lastmod>
|
||||||
</url>
|
</url>
|
||||||
<url>
|
<url>
|
||||||
<loc>https://www.ioccc.org/next/rules.md</loc>
|
<loc>https://www.ioccc.org/next/rules.md</loc>
|
||||||
<lastmod>2025-11-24T13:29:41+00:00</lastmod>
|
<lastmod>2025-11-27T07:11:14+00:00</lastmod>
|
||||||
</url>
|
</url>
|
||||||
<url>
|
<url>
|
||||||
<loc>https://www.ioccc.org/next/submit.html</loc>
|
<loc>https://www.ioccc.org/next/submit.html</loc>
|
||||||
@@ -16938,7 +16938,7 @@
|
|||||||
</url>
|
</url>
|
||||||
<url>
|
<url>
|
||||||
<loc>https://www.ioccc.org/status.html</loc>
|
<loc>https://www.ioccc.org/status.html</loc>
|
||||||
<lastmod>2025-11-26T06:28:00+00:00</lastmod>
|
<lastmod>2025-11-27T07:15:03+00:00</lastmod>
|
||||||
</url>
|
</url>
|
||||||
<url>
|
<url>
|
||||||
<loc>https://www.ioccc.org/status.json</loc>
|
<loc>https://www.ioccc.org/status.json</loc>
|
||||||
|
|||||||
Reference in new issue
Block a user