@@ -57,79 +57,108 @@ culpa qui officia deserunt mollit anim id est laborum.
5757
5858## Lists
5959
60+ Markdown doesn't have strict rules about how to process lists. When we moved
61+ from Jekyll to Hugo, we broke some lists. To fix them, keep the following in
62+ mind:
63+
64+ - Make sure you indent sub-list items ** 4 spaces** rather than the 2 that you
65+ ma be yused to. Counter-intuitively, you need to indent block-level content
66+ within a list item an extra 4 spaces too.
67+
68+ - To end a list and start another, you need a HTML comment block on a new line
69+ between the lists, flush with the left-hand border. The first list won't end
70+ otherwise, no matter how many blank lines you put between it and the second.
71+
6072### Bullet lists
6173
6274- This is a list item
6375* This is another list item in the same list
6476- You can mix ` - ` and ` * `
65- - To make a sub-item, indent two spaces.
66- - This is a sub-sub-item.
67-
77+ - To make a sub-item, indent two tabstops (4 spaces). ** This is different
78+ from Jekyll and Kramdown.**
79+ - This is a sub-sub-item. Indent two more tabstops (4 more spaces).
80+ - Another sub-item.
6881
82+ <!-- separate lists -->
6983
70- - This is a new list. It has two blank lines from the previous list, If it only
71- had one blank line, it would still show up as part of the previous list.
84+ - This is a new list. With Hugo, you need to use a HTML comment to separate two
85+ consecutive lists. ** The HTML comment needs to be at the left margin. **
7286- Bullet lists can have paragraphs or block elements within them.
7387
74- Just indent the content to be even with the text of the bullet point, rather
75- than the bullet itself.
88+ Indent the content to be one tab stop beyond the text of the bullet
89+ point. **This paragraph and the code block line up with the second `l` in
90+ `Bullet` above.**
7691
77- ``` bash
78- ls -l
79- ```
92+ ```bash
93+ ls -l
94+ ```
8095
81- - And a sub-list after some block-level content
96+ - And a sub-list after some block-level content
97+
8298- A bullet list item can contain a numbered list.
83- 1 . Numbered sub-list item 1
84- 2 . Numbered sub-list item 2
99+ 1 . Numbered sub-list item 1
100+ 2 . Numbered sub-list item 2
85101
86102### Numbered lists
87103
881041 . This is a list item
891052 . This is another list item in the same list. The number you use in Markdown
90106 does not necessarily correlate to the number in the final output. By
91107 convention, we keep them in sync.
92- 3 . For single-digit numbered lists, using two spaces after the period makes
108+ 3 . {{<note >}}
109+ For single-digit numbered lists, using two spaces after the period makes
93110 interior block-level content line up better along tab-stops.
111+ {{</note >}}
94112
113+ <!-- separate lists -->
95114
96-
97- 1 . This is a new list. It has two blank lines from the previous list, If it only
98- had one blank line, it would still show up as part of the previous list.
115+ 1 . This is a new list. With Hugo, you need to use a HTML comment to separate
116+ two consecutive lists. ** The HTML comment needs to be at the left margin.**
991172 . Numbered lists can have paragraphs or block elements within them.
100118
101- Just indent the content to be even with the text of the bullet point, rather
102- than the bullet itself.
119+ Just indent the content to be one tab stop beyond the text of the bullet
120+ point. ** This paragraph and the code block line up with the ` m ` in
121+ ` Numbered ` above.**
103122
104- ``` bash
105- $ ls -l
106- ```
107-
108- - And a sub-list after some block-level content
123+ ``` bash
124+ $ ls -l
125+ ```
126+
127+ - And a sub-list after some block-level content. This is at the same
128+ " level"
129+ more.
109130
110131
111132# ## Checklists
112133
134+ Checlists are technically bullet lists, but the bullets are suppressed by CSS.
135+
113136- [ ] This is a checklist item
114137- [x] This is a selected checklist item
115138
116139# # Code blocks
117140
118- You can create code blocks two different ways:
141+ You can create code blocks two different ways by surrounding the code block with
142+ three back-tick characters on lines before and after the code block. ** Only use
143+ back-ticks (code fences) for code blocks.** This allows you to specify the
144+ language of the enclosed code, which enables syntax highlighting. It is also more
145+ predictable than using indentation.
119146
120- - by indenting the entire code block 4 spaces from the content
147+ {{< warning > }}
148+ There is one situation where you need to use indentation for code blocks: when
149+ the contents of the code block contain lines starting with ` -` ` * `
150+ This is due to
151+ [blackfriday issue # 239](https://github.com/russross/blackfriday/issues/239).
152+ {{< /warning > }}
121153
122- this is a code block created by indentation
123-
124- - by surrounding the code block with three back-tick characters on lines before
125- and after the code block.
126154
127- ```
128- this is a code block created by back-ticks
129- ```
155+ ` ``
156+ this is a code block created by back-ticks
157+ ` ` `
130158
131159The back-tick method has some advantages.
132160
161+ - It works nearly every time
133162- It is more compact when viewing the source code.
134163- It allows you to specify what language the code block is in, for syntax
135164 highlighting.
@@ -143,6 +172,16 @@ grouping of back-ticks:
143172ls -l
144173` ` `
145174
175+ Common languages used in Kubernetes documentation code blocks include:
176+
177+ - ` bash` ` shell`
178+ - ` go`
179+ - ` json`
180+ - ` yaml`
181+ - ` xml`
182+ - ` none` for the block)
183+
184+
146185# # Links
147186
148187To format a link, put the link text inside square brackets, followed by the
0 commit comments