diff options
Diffstat (limited to 'content/personal/mis-design-test')
-rw-r--r-- | content/personal/mis-design-test/index.md | 306 |
1 files changed, 306 insertions, 0 deletions
diff --git a/content/personal/mis-design-test/index.md b/content/personal/mis-design-test/index.md new file mode 100644 index 0000000..c31e42d --- /dev/null +++ b/content/personal/mis-design-test/index.md | |||
@@ -0,0 +1,306 @@ | |||
1 | --- | ||
2 | title: "Design Test: Markdown Syntax" | ||
3 | category: mis | ||
4 | --- | ||
5 | |||
6 | - [Overview](#overview) | ||
7 | - [Philosophy](#philosophy) | ||
8 | - [Block Elements](#block-elements) | ||
9 | - [Paragraphs and Line Breaks](#paragraphs-and-line-breaks) | ||
10 | - [Headers](#headers) | ||
11 | - [Blockquotes](#blockquotes) | ||
12 | - [Lists](#lists) | ||
13 | - [Code Blocks](#code-blocks) | ||
14 | - [Span Elements](#span-elements) | ||
15 | - [Links](#links) | ||
16 | - [Emphasis](#emphasis) | ||
17 | - [Code](#code) | ||
18 | |||
19 | |||
20 | **Note:** This document is itself written using Markdown; you | ||
21 | can [see the source for it by adding '.text' to the URL](/projects/markdown/syntax.text). | ||
22 | |||
23 | ---- | ||
24 | |||
25 | ## Overview | ||
26 | |||
27 | ### Philosophy | ||
28 | |||
29 | Markdown is intended to be as easy-to-read and easy-to-write as is feasible. | ||
30 | |||
31 | Readability, however, is emphasized above all else. A Markdown-formatted | ||
32 | document should be publishable as-is, as plain text, without looking | ||
33 | like it's been marked up with tags or formatting instructions. While | ||
34 | Markdown's syntax has been influenced by several existing text-to-HTML | ||
35 | filters -- including [Setext](http://docutils.sourceforge.net/mirror/setext.html), [atx](http://www.aaronsw.com/2002/atx/), [Textile](http://textism.com/tools/textile/), [reStructuredText](http://docutils.sourceforge.net/rst.html), | ||
36 | [Grutatext](http://www.triptico.com/software/grutatxt.html), and [EtText](http://ettext.taint.org/doc/) -- the single biggest source of | ||
37 | inspiration for Markdown's syntax is the format of plain text email. | ||
38 | |||
39 | ## Block Elements | ||
40 | |||
41 | ### Paragraphs and Line Breaks | ||
42 | |||
43 | A paragraph is simply one or more consecutive lines of text, separated | ||
44 | by one or more blank lines. (A blank line is any line that looks like a | ||
45 | blank line -- a line containing nothing but spaces or tabs is considered | ||
46 | blank.) Normal paragraphs should not be indented with spaces or tabs. | ||
47 | |||
48 | The implication of the "one or more consecutive lines of text" rule is | ||
49 | that Markdown supports "hard-wrapped" text paragraphs. This differs | ||
50 | significantly from most other text-to-HTML formatters (including Movable | ||
51 | Type's "Convert Line Breaks" option) which translate every line break | ||
52 | character in a paragraph into a `<br />` tag. | ||
53 | |||
54 | When you *do* want to insert a `<br />` break tag using Markdown, you | ||
55 | end a line with two or more spaces, then type return. | ||
56 | |||
57 | ### Headers | ||
58 | |||
59 | Markdown supports two styles of headers, [Setext] [1] and [atx] [2]. | ||
60 | |||
61 | Optionally, you may "close" atx-style headers. This is purely | ||
62 | cosmetic -- you can use this if you think it looks better. The | ||
63 | closing hashes don't even need to match the number of hashes | ||
64 | used to open the header. (The number of opening hashes | ||
65 | determines the header level.) | ||
66 | |||
67 | |||
68 | ### Blockquotes | ||
69 | |||
70 | Markdown uses email-style `>` characters for blockquoting. If you're | ||
71 | familiar with quoting passages of text in an email message, then you | ||
72 | know how to create a blockquote in Markdown. It looks best if you hard | ||
73 | wrap the text and put a `>` before every line: | ||
74 | |||
75 | > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, | ||
76 | > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. | ||
77 | > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. | ||
78 | > | ||
79 | > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse | ||
80 | > id sem consectetuer libero luctus adipiscing. | ||
81 | |||
82 | Markdown allows you to be lazy and only put the `>` before the first | ||
83 | line of a hard-wrapped paragraph: | ||
84 | |||
85 | > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, | ||
86 | consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. | ||
87 | Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. | ||
88 | |||
89 | > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse | ||
90 | id sem consectetuer libero luctus adipiscing. | ||
91 | |||
92 | Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by | ||
93 | adding additional levels of `>`: | ||
94 | |||
95 | > This is the first level of quoting. | ||
96 | > | ||
97 | > > This is nested blockquote. | ||
98 | > | ||
99 | > Back to the first level. | ||
100 | |||
101 | Blockquotes can contain other Markdown elements, including headers, lists, | ||
102 | and code blocks: | ||
103 | |||
104 | > ## This is a header. | ||
105 | > | ||
106 | > 1. This is the first list item. | ||
107 | > 2. This is the second list item. | ||
108 | > | ||
109 | > Here's some example code: | ||
110 | > | ||
111 | > return shell_exec("echo $input | $markdown_script"); | ||
112 | |||
113 | Any decent text editor should make email-style quoting easy. For | ||
114 | example, with BBEdit, you can make a selection and choose Increase | ||
115 | Quote Level from the Text menu. | ||
116 | |||
117 | |||
118 | ### Lists | ||
119 | |||
120 | Markdown supports ordered (numbered) and unordered (bulleted) lists. | ||
121 | |||
122 | Unordered lists use asterisks, pluses, and hyphens -- interchangably | ||
123 | -- as list markers: | ||
124 | |||
125 | * Red | ||
126 | * Green | ||
127 | * Blue | ||
128 | |||
129 | is equivalent to: | ||
130 | |||
131 | + Red | ||
132 | + Green | ||
133 | + Blue | ||
134 | |||
135 | and: | ||
136 | |||
137 | - Red | ||
138 | - Green | ||
139 | - Blue | ||
140 | |||
141 | Ordered lists use numbers followed by periods: | ||
142 | |||
143 | 1. Bird | ||
144 | 2. McHale | ||
145 | 3. Parish | ||
146 | |||
147 | It's important to note that the actual numbers you use to mark the | ||
148 | list have no effect on the HTML output Markdown produces. The HTML | ||
149 | Markdown produces from the above list is: | ||
150 | |||
151 | If you instead wrote the list in Markdown like this: | ||
152 | |||
153 | 1. Bird | ||
154 | 1. McHale | ||
155 | 1. Parish | ||
156 | |||
157 | or even: | ||
158 | |||
159 | 3. Bird | ||
160 | 1. McHale | ||
161 | 8. Parish | ||
162 | |||
163 | you'd get the exact same HTML output. The point is, if you want to, | ||
164 | you can use ordinal numbers in your ordered Markdown lists, so that | ||
165 | the numbers in your source match the numbers in your published HTML. | ||
166 | But if you want to be lazy, you don't have to. | ||
167 | |||
168 | To make lists look nice, you can wrap items with hanging indents: | ||
169 | |||
170 | * Lorem ipsum dolor sit amet, consectetuer adipiscing elit. | ||
171 | Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, | ||
172 | viverra nec, fringilla in, laoreet vitae, risus. | ||
173 | * Donec sit amet nisl. Aliquam semper ipsum sit amet velit. | ||
174 | Suspendisse id sem consectetuer libero luctus adipiscing. | ||
175 | |||
176 | But if you want to be lazy, you don't have to: | ||
177 | |||
178 | * Lorem ipsum dolor sit amet, consectetuer adipiscing elit. | ||
179 | Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, | ||
180 | viverra nec, fringilla in, laoreet vitae, risus. | ||
181 | * Donec sit amet nisl. Aliquam semper ipsum sit amet velit. | ||
182 | Suspendisse id sem consectetuer libero luctus adipiscing. | ||
183 | |||
184 | List items may consist of multiple paragraphs. Each subsequent | ||
185 | paragraph in a list item must be indented by either 4 spaces | ||
186 | or one tab: | ||
187 | |||
188 | 1. This is a list item with two paragraphs. Lorem ipsum dolor | ||
189 | sit amet, consectetuer adipiscing elit. Aliquam hendrerit | ||
190 | mi posuere lectus. | ||
191 | |||
192 | Vestibulum enim wisi, viverra nec, fringilla in, laoreet | ||
193 | vitae, risus. Donec sit amet nisl. Aliquam semper ipsum | ||
194 | sit amet velit. | ||
195 | |||
196 | 2. Suspendisse id sem consectetuer libero luctus adipiscing. | ||
197 | |||
198 | It looks nice if you indent every line of the subsequent | ||
199 | paragraphs, but here again, Markdown will allow you to be | ||
200 | lazy: | ||
201 | |||
202 | * This is a list item with two paragraphs. | ||
203 | |||
204 | This is the second paragraph in the list item. You're | ||
205 | only required to indent the first line. Lorem ipsum dolor | ||
206 | sit amet, consectetuer adipiscing elit. | ||
207 | |||
208 | * Another item in the same list. | ||
209 | |||
210 | To put a blockquote within a list item, the blockquote's `>` | ||
211 | delimiters need to be indented: | ||
212 | |||
213 | * A list item with a blockquote: | ||
214 | |||
215 | > This is a blockquote | ||
216 | > inside a list item. | ||
217 | |||
218 | To put a code block within a list item, the code block needs | ||
219 | to be indented *twice* -- 8 spaces or two tabs: | ||
220 | |||
221 | * A list item with a code block: | ||
222 | |||
223 | <code goes here> | ||
224 | |||
225 | ### Code Blocks | ||
226 | |||
227 | Pre-formatted code blocks are used for writing about programming or | ||
228 | markup source code. Rather than forming normal paragraphs, the lines | ||
229 | of a code block are interpreted literally. Markdown wraps a code block | ||
230 | in both `<pre>` and `<code>` tags. | ||
231 | |||
232 | To produce a code block in Markdown, simply indent every line of the | ||
233 | block by at least 4 spaces or 1 tab. | ||
234 | |||
235 | This is a normal paragraph: | ||
236 | |||
237 | This is a code block. | ||
238 | |||
239 | Here is an example of AppleScript: | ||
240 | |||
241 | tell application "Foo" | ||
242 | beep | ||
243 | end tell | ||
244 | |||
245 | A code block continues until it reaches a line that is not indented | ||
246 | (or the end of the article). | ||
247 | |||
248 | Within a code block, ampersands (`&`) and angle brackets (`<` and `>`) | ||
249 | are automatically converted into HTML entities. This makes it very | ||
250 | easy to include example HTML source code using Markdown -- just paste | ||
251 | it and indent it, and Markdown will handle the hassle of encoding the | ||
252 | ampersands and angle brackets. For example, this: | ||
253 | |||
254 | <div class="footer"> | ||
255 | © 2004 Foo Corporation | ||
256 | </div> | ||
257 | |||
258 | Regular Markdown syntax is not processed within code blocks. E.g., | ||
259 | asterisks are just literal asterisks within a code block. This means | ||
260 | it's also easy to use Markdown to write about Markdown's own syntax. | ||
261 | |||
262 | ``` | ||
263 | tell application "Foo" | ||
264 | beep | ||
265 | end tell | ||
266 | ``` | ||
267 | |||
268 | ## Span Elements | ||
269 | |||
270 | ### Links | ||
271 | |||
272 | Markdown supports two style of links: *inline* and *reference*. | ||
273 | |||
274 | In both styles, the link text is delimited by [square brackets]. | ||
275 | |||
276 | To create an inline link, use a set of regular parentheses immediately | ||
277 | after the link text's closing square bracket. Inside the parentheses, | ||
278 | put the URL where you want the link to point, along with an *optional* | ||
279 | title for the link, surrounded in quotes. For example: | ||
280 | |||
281 | This is [an example](http://example.com/) inline link. | ||
282 | |||
283 | [This link](http://example.net/) has no title attribute. | ||
284 | |||
285 | ### Emphasis | ||
286 | |||
287 | Markdown treats asterisks (`*`) and underscores (`_`) as indicators of | ||
288 | emphasis. Text wrapped with one `*` or `_` will be wrapped with an | ||
289 | HTML `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML | ||
290 | `<strong>` tag. E.g., this input: | ||
291 | |||
292 | *single asterisks* | ||
293 | |||
294 | _single underscores_ | ||
295 | |||
296 | **double asterisks** | ||
297 | |||
298 | __double underscores__ | ||
299 | |||
300 | ### Code | ||
301 | |||
302 | To indicate a span of code, wrap it with backtick quotes (`` ` ``). | ||
303 | Unlike a pre-formatted code block, a code span indicates code within a | ||
304 | normal paragraph. For example: | ||
305 | |||
306 | Use the `printf()` function. | ||