IMPORTANT: Be sure to read the IOCCC rules and IOCCC -guidelines.
-Jump to: top
+These Markdown Guidelines are version 29.0 2025-11-26.
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 “remarks.md submission file”.
-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.
-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 entry uses a README.md
+markdown file as the basis for forming the index.html web page for
+that entry. All HTML 5 generated pages on the Official IOCCC website
+start with some markdown content. We no longer support older HTML
+standards and some of our guidelines help integrate winning entries into
+the website more easily.
See the markdown syntax guide. See also the CommonMark Spec. +See the FAQ on “remarks.md submission file”.
+Nevertheless, the IOCCC does have certain practices that we ask authors to +follow. Some of these relate to use of markdown directly and others relate +to injecting HTML into the markdown file.
+In the sections below, examples will mark by ❌ for the incorrect method +and ✔️ for preferred correct one.
remarks.md sections at level 3 (###), increasing for subsections up to 6 (######)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:
# Foo <=== no thank you
- ## Foo <=== no thank youInstead, start sections with 3 #s:
### Section 0For each subsection of the current section, add another #, up to 6, going back
-to 3 for new sections. For instance:
### Section 0
- ...
- #### 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.remarks.md sections at level 3If (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:
❌ # Section Reserved
+❌ ## Section Reserved
+✔️ ### Section Level 3
+✔️ #### Section Level 4
+✔️ ##### Section Level 5
+✔️ ###### Section Level 6name attributes in HTML <a>...</a> hyperlink elementsPlease do NOT use the HTML construct:
- <a name="string">...</a> <=== no thank youas 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 workFor 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
+<a name="anchor_name"></a> construct.❌ <a name="old_way">...</a>
+✔️ <span id="new_way">...</span><a>...</a>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 preferredJump to: top
-<a>...</a>❌ This <a href="#link_target>HTML link text</a> works, but we prefer
+✔️ [markdown link text](#link_target)<strike> or the <s> HTML elementPlease do NOT use the obsolete <strike> or the obsolete <s>
-(strikeout) HTML elements:
<strike>...</strike> <=== no thank you
- <s>...</s> <=== no thank youUse instead:
- <del>...</del>Jump to: top
-<strike> or <s>❌ <strike>striked through text</strike>
+❌ <s>HTML 5 striked through text</s>
+
+✔️ <del>HTML 5 striked through text</del>
+✔️ ~~markdown striked through text~~<u> HTML elementPlease do NOT use the obsolete <u> (underline) HTML element:
<u>...</u> <=== no thank youUse instead:
- <ins>...</ins>Jump to: top
+<u>❌ <u>old tags</u>
+✔️ <ins>HTML 5 tags</ins><tt> HTML elementPlease do NOT use the obsolete <tt>
-(teletype) HTML element:
<tt>The tt element is obsolete</tt> <=== no thank youInstead 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:
-``` <!---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:
-``` <!---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
+<tt>❌ <tt>obsolete HTML</tt>
+✔️ <span style="font-family: monospace;">monospace font</span>
+✔️ `markdown style monospace`❌ echo "This code block is NOT indented"We request that you indent the code block by multiples of four (4) +ASCII SPACES, never TAB (␉):
+✔️ 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.Alternatively its possible to use ``` marks, without the initial
+four (4) space indentation. This is usually the better method.
✔️ ```
+✔️ The same thing applies to any markdown block bracketed by ``` lines.
+✔️ ```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 +
Please do NOT indent with ASCII TABs (␉), OR use any ASCII TAB +(␉) 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:
+If you need to indent two (2) or more levels, use multiples of four (4) +ASCII SPACES.
```
- Please do **NOT** use ASCII tabs in markdown files. <=== no thank you
- Please do **NOT** indent markdown with ASCII tabs. <=== no thank you
+❌ ␉Please do **NOT**␉use ASCII tabs␉in markdown files.
+❌ ␉␉Please do **NOT** indent markdown with ASCII tabs.
- We don't mind tabs in general, <=== no thank you
- We just ask that you NOT use them in markdown files.
+❌ ␉We don't␉mind␉tabs␉in␉general,
+❌ ␉We just ask that you NOT use them in markdown files.
```And to clarify, we are only talking about markdown files, -not C code or any other non-markdown content:
- printf("It is fine to use tabs in Obfuscated C code.\n");
- /* if you wish */
+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
-
-Tip for vim users
-
-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 " ...expand tab into 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 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.
-Please use HTML comments to specify a language for a code block
+
+
+
-We request that fenced markdown code
-blocks
+
Use HTML comments for code block language syntax.
+We request that fenced markdown code blocks
NOT specify a language directly.
-For example:
-```c <=== no thank you
- int main(void) {return 0;}
-```
+❌ ```c
+❌ int main(void) {return 0;}
+❌ ```
Instead, put the language inside an HTML comment, separated from the
markdown code block starting fence by a space:
-``` <!---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
+
✔️ ```<!---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 add trailing slash to void HTML elements
+
+
+Ensure blank line between code block and text.
+Please do NOT place text on the next line after a markdown code
+block. Instead, place a blank line after the end of a markdown code
+block as this makes it easier to detect when markdown code blocks are
+NOT properly indented.
+ ```
+ 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.
+
+
-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 markdown like these:
- <br/> <=== no thank you
+Do not add trailing slash to void HTML tags.
+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.
+❌ <br/>
+❌ <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
-
- <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, respectively:
- <br>
-
- <hr>
-
- <img src="1984-anonymous-tattoo.jpg"
- alt="image of a tattoo of the 1984 anonymous C code"
- width=600 height=401>
-Jump to: top
-
+✔️ <br>
+✔️ <hr>
+✔️ <img src="1984-anonymous-tattoo.jpg" alt="image of a tattoo of
+ the 1984 anonymous C code" width=600 height=401>
-Please do NOT use a TRAILING backslash (\) outside of a code block
+
+
+
-Unless the line is inside a markdown code block, please do NOT
-end a markdown line with a trailing backslash (\). Instead use
-a trailing <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
-
+Do not use a trailing backslash outside of a code block
+Unless the line is inside a markdown code block, please do NOT end
+a markdown line with a trailing backslash (\). Instead use a trailing
+<br>.
+❌ In markdown,\
+❌ do NOT use trailing\
+❌ backslashes outside of\
+❌ a code block
+
+✔️ In markdown,<br>
+✔️ use trailing<br>
+✔️ br's outside of<br>
+✔️ a code block
+
+✔️ ```
+✔️ This is OK\
+✔️ inside a\
+✔️ markdown code\
+✔️ block
+✔️ ```
+
+✔️ `This is OK\`
+Doing it this way will prevent pandoc(1) from generating deprecated
+HTML elements such as <br />.
-Please do NOT use markdown style images
+
-
-Please do NOT use the markdown embedded image element.
+Do not use markdown style images
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
+❌ 
+
+✔️ <img src="filename.png"
+ alt="describe the filename.png image for someone who cannot view it"
+ width=PIXEL_WIDTH height=PIXEL_HEIGHT>
+
+ Which allows for HTML <img> attributes `alt=`, `width=` and `length=`.
+The problem is 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.
-
-
-Please do NOT use markdown style horizontal lines
-
-
+
+Replace markdown style horizontal lines.
Please do NOT use --- style lines in markdown to create horizontal
lines or to separate sections.
-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.
+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
+❌ * * *
+❌ - - -
+❌ ---
+
+ Regular divider...
+✔️ <hr>
+
+ A short divider...
+✔️ <hr style="width:10%;text-align:left;margin-left:0">
-Please do NOT put a LITERAL “(” or “)” in markdown link titles
+
-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
+Do not put a literal “(” or “)” in markdown link titles
+❌ [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)
-Please do NOT end markdown links with “))”
+
-Please do NOT end a markdown link with a double closed parenthesis “))”.
+Do not end markdown links with “))”
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 IMMEDIATE (very next) line after a markdown code block
-
-
-
-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;
- }
-```
+❌ [some text](https://example.com/foo_(bar))
+✔️ [some text](https://example.com/foo_(bar))
-C compilers cannot be given a -Wno-main-arg-errors flag.
-BTW: Please note the blank line after the code block.
-Jump to: top
+❌ This thing, ([some text](some/path)), is NOT ideal.
+✔️ This thing, [some text](some/path), is better.
-Please use _ for italics in markdown
+
-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**_
-BTW: the astute reader might notice that some cases of * for italic might
-have slipped through. We do ask you, however, to please observe this rule, as
-best you can.
+
Use _ for italics in markdown
+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.
+❌ *this text is italic*
+✔️ _this text is 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 might have slipped through. We do ask you, however, to please
+observe this rule, as best you can.
diff --git a/markdown.md b/markdown.md
index 8049760c0..170f4a33a 100644
--- a/markdown.md
+++ b/markdown.md
@@ -3,7 +3,7 @@
## 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**.
@@ -217,7 +217,7 @@ block as this makes it easier to detect when markdown code blocks are
return foo;
}
✔️ ```
-✔️
+✔️
✔️ C compilers cannot be given a -Wno-main-arg-errors flag.
````
diff --git a/sitemap.xml b/sitemap.xml
index 546a1488b..7fbedb885 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -16810,11 +16810,11 @@
https://www.ioccc.org/markdown.html
- 2025-07-26T18:35:07+00:00
+ 2025-11-27T07:21:50+00:00
https://www.ioccc.org/markdown.md
- 2025-07-12T17:16:31+00:00
+ 2025-11-27T07:21:43+00:00
https://www.ioccc.org/news.html
@@ -16826,11 +16826,11 @@
https://www.ioccc.org/next/guidelines.html
- 2025-11-24T13:29:41+00:00
+ 2025-11-27T07:11:14+00:00
https://www.ioccc.org/next/guidelines.md
- 2025-11-24T13:29:41+00:00
+ 2025-11-27T07:11:14+00:00
https://www.ioccc.org/next/index.html
@@ -16870,11 +16870,11 @@
https://www.ioccc.org/next/rules.html
- 2025-11-24T13:29:41+00:00
+ 2025-11-27T07:11:14+00:00
https://www.ioccc.org/next/rules.md
- 2025-11-24T13:29:41+00:00
+ 2025-11-27T07:11:14+00:00
https://www.ioccc.org/next/submit.html
@@ -16938,7 +16938,7 @@
https://www.ioccc.org/status.html
- 2025-11-26T06:28:00+00:00
+ 2025-11-27T07:15:03+00:00
https://www.ioccc.org/status.json