These [IOCCC markdown guidelines](markdown.html) are version **28.0 2024-10-25**.
IMPORTANT: Be sure to read the IOCCC rules and IOCCC guidelines.
Jump to: top
The IOCCC makes extensive use of markdown.
For example, when submitting to the IOCCC
we have people
submit remarks about their entry in markdown format. Every
winning IOCCC entry uses a README.md markdown file
as the basis for forming the index.html web page for that entry.
All generated HTML pages on the Official IOCCC website
start with some markdown content.
See the markdown syntax guide. See also the CommonMark Spec. See the FAQ on "how to submit".
Nevertheless, the IOCCC does have certain practices that we ask authors to follow. Some of these relate to use of markdown directly and others relate to injecting HTML into the markdown file.
In particular there are things we ask people to please NOT use in markdown files for the IOCCC:
Jump to: top
Please do NOT use the HTML construct:
<a name="string">...</a> <=== no thank you
as those are NOT part of the HTML 5 standard.
Instead use:
<div id="string">...</div>
where the ... is the HTML you want to "name". The <div>
encapsulates the HTML you want to name: i.e., the target of some
<a href="#string"> or some other <a href="URL#string">
for the given page URL.
There are certain markdown constructs that CANNOT have an internal <div id="string">...</div> element.
An example is headings (lines that start with a #). For example:
# <div id="string">THIS WILL NOT WORK!</div> <=== this will not work
For things like headings, you have to surround them with the <div id="string">...</div> element, as in:
<div id="string">
# This will work
</div>
While some browsers will still recognize the HTML construct <a name="string">...</a>, it is possible they MIGHT NOT in the future.
Jump to: top
It is easier and preferred to use markdown links rather than HTML <a>..</a>
anchors.
Instead of:
Use of <a href="#links>HTML anchors</a>
is one option, however ...
[markdown links](#links) are easier and preferred
Jump to: top
Please do NOT use the obsolete <strike> or the obsolete <s>
(strikeout) HTML elements:
<strike>...</strike> <=== no thank you
<s>...</s> <=== no thank you
Use instead:
<del>...</del>
Jump to: top
Please NOT use the obsolete <u> (underline) HTML element:
<u>...</u> <=== no thank you
Use instead:
<ins>...</ins>
Jump to: top
Please do NOT use the obsolete <tt>
(teletype) HTML element:
<tt>The tt element is obsolete</tt> <=== no thank you
Instead use either a monospaced <span> or an inline markdown code block:
<span style="font-family: monospace;">Use of a monospaced font
is one option,
however ... </span>
We recommend using the inline markdown code block method instead:
Using the `inline markdown code block` is easier and is **preferred**.
Jump to: top
Please do NOT start code blocks at the first column.
For example:
``` <%%NO_COMMENT%%!---sh-->
echo "This code block is NOT indented" <=== no thank you
```
We request that you indent the code block by multiples of 4 ASCII SPACES:
``` <%%NO_COMMENT%%!---sh-->
echo "This code block is indented by mutiples of 4 spaces"
# The top level starts with a 4 ASCII space indent.
#
# Only indent with multiples of 4 ASCII spaces.
# 2nd level indent needs 8 ASCII spaces (no tabs).
# 3rd level indent needs 12 ASCII spaces (no tabs).
# etc.
```
Moreover:
```
The same thing applies to any markdown block surrounded by ``` lines.
```
Please do NOT indent using ASCII tab characters in markdown files.
Jump to: top
Please do NOT indent with ASCII tabs, OR use any ASCII tab characters anywhere inside a markdown file.
While we have nothing against the ASCII tab character in general, we have discovered that ASCII tab characters create problems when used as part of the leading whitespace within a markdown file.
If you need to indent 2 or more levels, use multiples of 4 ASCII SPACES.
For example:
```
Please do **NOT** use ASCII tabs in markdown files. <=== no thank you
Please do **NOT** indent markdown with ASCII tabs. <=== no thank you
We don't mind tabs in general, <=== no thank you
We just ask that you NOT use them in markdown files.
```
And to clarify, we are only talking about markdown files, not C code or any other non-markdown content:
printf("It is fine to use tabs in Obfuscated C code.\n");
/* if you wish */
// We ask that you to NOT use ASCII tab characters in your remarks.md writeup,
// or in any other markdown files within your entry, please.
NOTE: Again, you are perfectly welcome to use ASCII tab characters in your C code and other non-markdown files. We simply ask that you do NOT use any ASCII tab characters in markdown files.
Jump to: top
If you use vim you can put in your .vimrc file (usually ~/.vimrc) the
following settings to make sure the tabs are not put in without you noticing:
set tabstop=8 " a tab is 8 spaces (or whatever you wish it to be set to)
set softtabstop=4 " ...but when inserting/backspacing use 4 spaces
set shiftwidth=4 " ...and auto-indent 4 spaces (when autoindent is set)
set expandtab " ...but don't expand tab to spaces.
If you have file type detection enabled you can, if you prefer, have these settings set just for markdown files:
autocmd! Filetype markdown setlocal set tabstop=8 softtabstop=4 shiftwidth=4 expandtab
or so.
This will prevent the tab key from inserting tabs; rather it will insert 4 spaces.
To VERIFY that there are no tabs in a file you may do, in command mode:
/\t
If you're in insert mode hit ESC first.
Jump to: top
We request that fenced markdown code blocks NOT specify a language directly.
For example:
```c <=== no thank you
int main(void) {return 0;}
```
Instead, put the language inside an HTML comment, separated from the markdown code block starting fence by a space:
``` <%%NO_COMMENT%%!---c-->
int main(void) {return 0;}
```
IMPORTANT: The initial ` ` ` must be followed by an ASCII SPACE,
and THEN an opening <!--- (a "<", a "!" and then three "-"s), and
THEN the language and FINALLY a closing "-->" (two "-"s
followed by a ">").
Jump to: top
Please do NOT use a trailing slash on void HTML elements.
See also this note on trailing slashes in void-element start tags.
The trailing slash on void HTML elements has no effect and interacts badly with unquoted attribute values.
For example, please do NOT use:
<br/> <=== no thank you
Instead use just:
<br>
And for example, please do NOT use:
<hr/> <=== no thank you
Instead use just:
<br>
and
<hr>
And for example, please do NOT use:
<img src="1984-anonymous-tattoo.jpg"
alt="image of a tattoo of the 1984 anonymous C code"
width=600 height=401 /> <=== no thank you
Instead use just:
<img src="1984-anonymous-tattoo.jpg"
alt="image of a tattoo of the 1984 anonymous C code"
width=600 height=401>
etc.
Jump to: top
Unless the line is inside a markdown code block, please do NOT
end a markdown line with a trailing backslash (\). Instead use
a trailing <br>.
Instead of:
In markdown,\ <=== no thank you
do NOT use trailing\
backslashes outside of\
a code block
use:
In markdown,<br>
use trailing<br>
br's outside of<br>
a code block
Again, use of a trailing backslash (\) inside a markdown code block is fine:
```
This is OK\
inside a\
markdown code\
block
```
as is:
`This is OK\`
Doing it this way will prevent pandoc(1) from generating deprecated HTML
elements such as <br />.
Jump to: top
Please do NOT use the markdown embedded image element.
Instead of using this markdown element to embed an image:
 <=== no thank you
Use an <img> HTML element with alt=, width= and length=
attributes:
<img src="filename.png"
alt="describe the filename.png image for someone who cannot view it"
width=PIXEL_WIDTH height=PIXEL_HEIGHT>
For example, instead of:
 <=== no thank you
use this HTML:
<img src="1984-anonymous-tattoo.jpg"
alt="image of a tattoo of the 1984 anonymous C code"
width=600 height=401>
The problem goes beyond the fact that pandoc(1) generates problematic
HTML from the markdown image construct, the resulting HTML does NOT
have width and height information so browsers have to slow down
on rendering text around the image until it can internally determine
the image size.
Jump to: top
Please do NOT use --- style lines in markdown to create horizontal
lines or to separate sections.
Unless something is inside a markdown code block, do NOT start a
line with 3 or more dashes ("-"s).
Such markdown causes pandoc(1) to generate <hr />. The <hr /> has no
effect in standard HTML 5 and interacts badly with unquoted attribute values.
If a horizontal line is really needed, use:
<hr>
If a short line is needed, use:
<hr style="width:10%;text-align:left;margin-left:0">
Jump to: top
Please do NOT use literal parentheses inside markdown link titles.
Instead of:
[some (text)](https://example.com/curds) <=== no thank you
use:
[some (text)](https://example.com/curds)
Instead of:
[ls(1)](https://example.com/ls-man-page.1) <=== no thank you
use:
[ls(1)](https://example.com/ls-man-page.1)
Jump to: top
Please do NOT end a markdown link with a double closed parenthesis "))".
Markdown links that end in "))" complicate parsing and sometimes lead
to incorrect URLs or file paths.
Instead of:
[some text](https://example.com/foo_(bar)) <=== no thank you
use:
[some text](https://example.com/foo_(bar))
As another example, instead of:
This thing, ([some text](some/path)), is NOT ideal. <=== no thank you
use:
This thing, [some text](some/path), is better.
Jump to: top
Please do NOT place text on the next line after a markdown code block. Instead, place a blank line after the end of a markdown code block as this makes it easier to detect when markdown code blocks are NOT properly indented.
Instead of:
```
int
main(int foo)
{
return foo;
}
```
C compilers cannot be given a -Wno-main-arg-errors flag. <=== no thank you
use:
```
int
main(int foo)
{
return foo;
}
```
C compilers cannot be given a -Wno-main-arg-errors flag.
BTW: Please note the blank line after the code block.
Jump to: top
Please do NOT use * (single asterisk) for italics in markdown. Instead use
an underscore (_). Using an asterisk can complicate parsing and sometimes lead
to incorrect results. This can especially go for when it is bold and
italic.
For example, instead of:
*this text is italic* <=== no thank you
use:
_this text is italic_
Another example, for bold italic:
Do NOT use:
***this text is bold italic*** <=== no thank you
Instead use:
**_this text is bold italic_**
or:
_**this text is bold italic**_