-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathMarkdownTutorial.html
293 lines (282 loc) · 13.9 KB
/
MarkdownTutorial.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<title>Markdown Tutorial</title>
<style type="text/css">
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
</style>
<link rel="stylesheet" href="pandoc.css">
<!--[if lt IE 9]>
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
<![endif]-->
</head>
<body>
<header>
<h1 class="title">Markdown Tutorial</h1>
</header>
<p><a href="https://3geek14.github.io/Realms/">Index</a></p>
<h1 id="markdown-tutorial">Markdown Tutorial</h1>
<p>Markdown is one of the simpler languages to use for formatting text. Because we’re tracking things in git, we’re using plaintext, so we need to use some language to specify the formatting. One of the design goals of markdown is to match what people would normally do in plaintext, which is a large factor for why I picked it. For example, underscores around text are used for emphasis.</p>
<pre><code>_This is italics._ __This is bold.__</code></pre>
<div class="example">
<p><em>This is italics.</em> <strong>This is bold.</strong></p>
</div>
<p>You might find tutorials online with other ways to emphasize things, such as with asterisks. Markdown has a lot of features we won’t use, so this guide will only show you some ways of doing certain things that can be done in other ways. For the sake of consistency, please try to use the same methods shown here.</p>
<p>There are many different types of markdown. The specific one we’re using is Pandoc’s version of markdown. Pandoc is a tool designed to convert between a lot of different formats, and its version of markdown has basically everything we want to use for the Omnibus. GitHub has its own version, which is very similar, but it’s missing a couple things.</p>
<p>As with many plaintext formats, a blank line is needed to create a new paragraph. The reason that a single new line won’t create a new paragraph is so that we have the option to keep individual lines of code shorter. This isn’t strictly necessary, but it does make it a little easier to see what changed using git’s tool for showing differences between versions (called <code>diff</code>). As an example of this:</p>
<pre><code>This is one long paragraph
that's super long. So long
that whoever wrote it wanted
to split it up amongst a
bunch of different lines.
This is a new paragraph.</code></pre>
<div class="example">
<p>This is one long paragraph that’s super long. So long that whoever wrote it wanted to split it up amongst a bunch of different lines.</p>
<p>This is a new paragraph.</p>
</div>
<p>As a rough guideline, try to keep lines of code no longer than 80 characters. Don’t worry too much about this, as things will change when text is made red or black. It’s a guideline, and we trust each other to use good judgement.</p>
<h3 id="headings">Headings</h3>
<p>There are three levels of headings we use in the Omnibus. Section numbers are the biggest, subsection numbers are next, and then come things that aren’t numbered. Here are some examples from the Omnibus:</p>
<pre><code># 1: General Player Information #
## 1.3: How Do I Start Playing? ##
### Realms Events ###</code></pre>
<div class="example">
<h1 id="general-player-information-1">1: General Player Information</h1>
<h2 id="how-do-i-start-playing">1.3: How Do I Start Playing?</h2>
<h3 id="realms-events">Realms Events</h3>
</div>
<p>If you’re familiar with HTML, these correspond with <code>h1</code>, <code>h2</code>, and <code>h3</code> tags. The first heading is the most important, so it’s biggest. If you look at the code so far, you’ll see headings are done a little bit differently. They have something extra at the end:</p>
<pre><code># 1: General Player Information # {#general-player-information}</code></pre>
<div class="example">
<h1 id="general-player-information">1: General Player Information</h1>
</div>
<p>The point of this is so we can put in links to specific parts of the document. Markdown will automatically do this for headings, but it won’t always pick quite the same name that we would pick. Also, specifying it makes it easier to copy and paste.</p>
<p>Speaking of links, how do we make them? There are two parts: the text that should direct to somewhere else, and the place it points to (the target). Headings are given targets as shown above, but we can make other things targets as well.</p>
<pre><code>[This is a link target]{#my-link-target}
This is a [link](#my-link-target) to a target.
This is a [link](https://www.realmsnet.net/) to RealmsNet.
This is an email address: <[email protected]>.</code></pre>
<div class="example">
<p><span id="my-link-target">This is a link target</span></p>
<p>This is a <a href="#my-link-target">link</a> to a target.</p>
<p>This is a <a href="https://www.realmsnet.net/">link</a> to RealmsNet.</p>
<p>This is an email address: <a href="mailto:[email protected]">[email protected]</a>.</p>
</div>
<p>To make a link target, use curly braces (<code>{}</code>). To navigate to a link, use parentheses (<code>()</code>). Email addresses are a little different; they use less than and greater than (<code><></code>).</p>
<p>Tables are kind of messy. It’s not super easy to make a table in plaintext, and it usually comes out looking pretty bulky. The table’s we’re using are called grid tables, because we draw a grid in the code. Yes, things have to line up for it to work. If you’re having trouble getting a table to work, feel free to make me do it, because I’m the one who picked markdown. Of course, the OEC is allowed to reformat things, so if you think of a way to present the same information without a table, feel free to try it out.</p>
<pre><code>+----------+----------+------------------------+
| Column 1 | Column 2 | Wider Column |
+==========+==========+========================+
| apple | banana | lots of text |
| | | that doesn't |
| | | fit on one |
| | | row of code |
+----------+----------+------------------------+
| text\ | ugh | tables suck |
| with an | | |
| explicit | | |
| line | | |
| break | | |
+----------+----------+------------------------+</code></pre>
<p>And let’s look at what that turns into.</p>
<div class="example">
<table style="width:65%;">
<colgroup>
<col style="width: 15%" />
<col style="width: 15%" />
<col style="width: 34%" />
</colgroup>
<thead>
<tr class="header">
<th>Column 1</th>
<th>Column 2</th>
<th>Wider Column</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>apple</td>
<td>banana</td>
<td>lots of text that doesn’t fit on one row of code</td>
</tr>
<tr class="even">
<td>text<br />
with an explicit line break</td>
<td>ugh</td>
<td>tables suck</td>
</tr>
</tbody>
</table>
</div>
<p>So yeah, tables kind of suck. The relative widths of the columns in the code becomes the relative widths of the columns in the result. If the table doesn’t use the top row as labels, replace the equals signs (<code>=</code>) with hyphens (<code>-</code>).</p>
<p>Column alignment is done by placing colons on the row with equals signs (or the top row, if there’s header row).</p>
<pre><code>+------+-------+--------+
| Left | Right | Center |
+:=====+======:+:======:+
| left | right | center |
+------+-------+--------+
+:-----+------:+:------:+
| Left | Right | Center |
+------+-------+--------+
| left | right | center |
+------+-------+--------+</code></pre>
<div class="example">
<table style="width:33%;">
<colgroup>
<col style="width: 9%" />
<col style="width: 11%" />
<col style="width: 12%" />
</colgroup>
<thead>
<tr class="header">
<th style="text-align: left;">Left</th>
<th style="text-align: right;">Right</th>
<th style="text-align: center;">Center</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">left</td>
<td style="text-align: right;">right</td>
<td style="text-align: center;">center</td>
</tr>
</tbody>
</table>
<table style="width:33%;">
<colgroup>
<col style="width: 9%" />
<col style="width: 11%" />
<col style="width: 12%" />
</colgroup>
<tbody>
<tr class="odd">
<td style="text-align: left;">Left</td>
<td style="text-align: right;">Right</td>
<td style="text-align: center;">Center</td>
</tr>
<tr class="even">
<td style="text-align: left;">left</td>
<td style="text-align: right;">right</td>
<td style="text-align: center;">center</td>
</tr>
</tbody>
</table>
</div>
<p>Next come lists. There are three different types of lists we use in the Omnibus. The first is bulleted lists, which is most common. Begin each item with an asterisk (<code>*</code>), and make sure there’s an empty line before the list.</p>
<pre><code>* This is the first list item.
* This is the next one.
* This on has enough text to be
multiple lines of code.
* This is another list item.</code></pre>
<div class="example">
<ul>
<li>This is the first list item.</li>
<li>This is the next one.</li>
<li>This on has enough text to be multiple lines of code.</li>
<li>This is another list item.</li>
</ul>
</div>
<p>We also use numbered lists. We so far only use this for the rules we play and fight by. For numbered lists, specify the number for the first item, and then use the number symbol (<code>#</code>) for later items.</p>
<pre><code>1. This is the first item.
#. This is the second item.
#. Notice the period after the number.
Put some text in to separate the lists.
11. This is a new list beginning with 11.
#. Notice that there's an extra space now
to keep things aligned.</code></pre>
<div class="example">
<ol type="1">
<li>This is the first item.</li>
<li>This is the second item.</li>
<li>Notice the period after the number.</li>
</ol>
<p>Put some text in to separate the lists.</p>
<ol start="11" type="1">
<li>This is a new list beginning with 11.</li>
<li>Notice that there’s an extra space now to keep things aligned.</li>
</ol>
</div>
<p>Finally we have soemthing called a description list. The idea behind this is for lists where you want to name each item rather than numbering them. Sure, you could use a bulleted list and start each one with some bold text, but this way looks more <em>classy</em>. There are some places we don’t use these where we probably should.</p>
<pre><code>Italics
: Use a single underscore around text
to make it italics, like _this_.
Bold
: Use double underscores around text
to make it bold, like __this__.
Description Lists
: Put the name of something on one
line, then put the description on
the next line. The first line of
the description should begin with a
colon, and all the lines of the
description should line up. Start
new descriptions with a blank line
before them.</code></pre>
<div class="example">
<dl>
<dt>Italics</dt>
<dd>Use a single underscore around text to make it italics, like <em>this</em>.
</dd>
<dt>Bold</dt>
<dd>Use double underscores around text to make it bold, like <strong>this</strong>.
</dd>
<dt>Description Lists</dt>
<dd>Put the name of something on one line, then put the description on the next line. The first line of the description should begin with a colon, and all the lines of the description should line up. Start new descriptions with a blank line before them.
</dd>
</dl>
</div>
<p>You can also nest lists. This currently only comes up in the Undeath part of Basic Magic Effects Everyone Should Know, I think.</p>
<pre><code>* This is the main list.
* This list has bullet points.
* This item has a sub list.
* This bullet point will look
different.
* Because this is a sub list.
* This item has a numbered sub list.
5. For some reason, this sublist
starts at five.
#. No good reason, other than to
show it can be done.
#. Let's go deeper, shall we?
* Sub sub lists never indicate
anything bad, right? They're
super clear.
* This is the final item.</code></pre>
<div class="example">
<ul>
<li>This is the main list.</li>
<li>This list has bullet points.</li>
<li>This item has a sub list.
<ul>
<li>This bullet point will look different.</li>
<li>Because this is a sub list.</li>
</ul></li>
<li>This item has a numbered sub list.
<ol start="5" type="1">
<li>For some reason, this sublist starts at five.</li>
<li>No good reason, other than to show it can be done.</li>
<li>Let’s go deeper, shall we?
<ul>
<li>Sub sub lists never indicate anything bad, right? They’re super clear.</li>
</ul></li>
</ol></li>
<li>This is the final item.</li>
</ul>
</div>
<p>One final thing about markdown. We need to have a way to specify text that was added this year. The way to do this looks very similar to a link target. The reason for this is that the HTML is very similar. To make something red, we label it as <code>new</code>. We do this as follows:</p>
<pre><code>[This sentence is new.]{.new}
This sentence is old. This
sentence had something
[changed]{.new}.</code></pre>
<div class="example">
<p><span class="new">This sentence is new.</span> This sentence is old. This sentence had something <span class="new">changed</span>.</p>
</div>
<p>Technically, this doesn’t do anything by itself. However, there’s a CSS document in the github repository that will look for anything called <code>new</code>, and it’ll give that a red underline. This is something that we have the authority to change, since it’s formatting. Also, I don’t see anything in the Omnibus that specifies that we need to do this, but it’s a long-standing convention to label what’s new. The reason I chose to do this instead of red text is simply because links are blue, and I think this makes it easier to see what’s going on when there’s new text that has a link.</p>
</body>
</html>