¶ About Markdown
Markdown is a markup language which allows users to create formatted documents while only writing in plaintext. It was created in 2004 as a way to write formatted text which could easily be converted to HTML.
Markdown is very useful for creating documents when a user wants to write text without the use of a full word processor (e.g. a .docx file), or an HTML editor.
There are many benefits to markdown. Since markdown uses plaintext, it is a very portable file type, and can be very easily converted to many other files (e.g. HTMLs, PDFs, or files). You can download any of the files on this website as a markdown file, and then render the file using a markdown editor using any theme or style that you want.
The main benefit on this wiki, however, is consistency. The use of markdown syntax ensures that pages keep the same style. More importantly, it makes it easier for anyone to make modifications to pages, even if they weren't the ones who originally wrote it.
The rest of this page goes in-depth on both common markdown syntax and some special markdown add-ons which pertain specifically to this wiki. By the end of this tutorial, you will be able to create markdown pages with images, text-info boxes, code segments, document links, headers, titles, and more.
If you want to explore all of the possible features, the tutorial here is not exhaustive. Visit this link to learn more:
https://docs.requarks.io/en/editors/markdown
¶ Markdown Editing Syntax
When you enter the markup editor, you will see the text editor on the left side of the screen, and the final rendered view on the right.
There is a toolbar at the top and left side of the page, which allows you to bolden, italicize, or otherwise edit your text. It should be self-explanatory, however the syntax of a markup webpage is not. The rest of this section details markup syntax, and how to manually add text decoration, headers, code segments, equations, and more.
Whenever you edit a webpage, ensure you regularly save the page with ctrl + s or ⌘ + s, or click the save button at the top right of the page. Work does not autosave, and you will lose progress if you close/refresh the page without saving.
¶ Basic Syntax
Markup-based text editors use symbols to denote titles, links, and other special text features.
To make text italicized, you can encase it with the * symbol. For example, if you wanted to italizice the word duck, you would type *duck* into the text editor.
To make text bold, you can encase it with **. For example, to bold the word duck, you can type **duck** into the text editor.
For a strikethrough, encase text with the ~~ symbols.
¶ Headers
A header line can be added by placing the # symbol at the beginning of the line.
To insert a header, insert a # symbol before the text. If you want to make a section called "How to pick up a duck," you would type the following into the text editor:
# How to Pick Up a Duck
To create a subheader, use two # symbols instead of one, like so:
## Step 1 - Asking the Duck for Permission
You can create up to a level 6 subheader, with 6 # symbols:
###### What to do if the duck has an Infinity Gauntlet
¶ Lists
A non-ordered list (aka bullet points) can be denoted with the - symbol. To make a list, simply write each new point on a new line, with the - symbol preceding it:
### Tips:
- Speak to the duck in a calm manner
- Never insult your duck, as it is very mean
The text above results in:
¶ Tips:
- Speak to the duck in a calm manner
- Never insult your duck, as it is very mean
¶ Equations
A single-line equation or variable can be inserted using . Encase any equations inside the $ sign. For example, $\frac{1}{x}$ will insert the fraction into the line.
A multi-line equation or variable can be inserted using two $ symbols. For example, typing $$\frac{\pi^{2}}{6}$$ on its own line will insert this fraction:
¶ Code Segments
A single-line code segment can be denoted with the backtick ` symbol, found below the esc key. For example, int duck = 72.
A multi-line code segment can be denoted with three backtick ``` symbols instead of one. After the first ```, denote the programming language you're using. For example:
```java
if(duck > 0)
{
system.out.println("duck");
}
```
The result:
if(duck > 0)
{
system.out.println("duck");
}
```python
if duck > 0:
print('duck')
```
The result:
if duck > 0:
print('duck')
```c
if(duck > 0)
{
printf("duck\n");
}
```
The result:
if(duck > 0)
{
printf("duck\n");
}
```cpp
if(duck > 0)
{
std::cout << "duck\n";
}
```
The result:
if(duck > 0)
{
std::cout << "duck\n";
}
```javascript
if(duck > 0)
{
console.log("duck");
}
```
The result:
if(duck > 0)
{
console.log("duck");
}
¶
Always use tab for code indentations, never spaces. This will mess up the formatting.
¶ Tabsets
A set of tabs can be created by adding the keyword {.tabset} after any header line. Every subheader under this "main" header becomes a new tab. For example, the following text segment:
### Birds other than ducks {.tabset}
#### Geese
Canadian Geese live in parks. Unlike ducks, these guys love to chase and hiss at any bystanders. Don't be like them.
#### Seagulls
Somehow worse than Geese. They like to steal food from unsuspecting beachgoers. Are also very loud. Beware.
#### Chickens
Quite friendly. They're quite good with fries.
### Conclusion
Ducks are the best. Quack
Will generate the following tabs, with the "conclusion" section following the tabs:
Canadian Geese live in parks. Unlike ducks, these guys love to chase and hiss at any bystanders. Don't be like them.
Somehow worse than Geese. They like to steal food from unsuspecting beachgoers. Are also very loud. Beware.
Quite friendly. They're quite good with fries.
¶ Conclusion
Ducks are the best. Quack.
¶ Images
You can upload your own images by clicking the "assets" folder on the left toolbar, and insert them into the page. Any image file type, such as .png or .jpeg, will be rendered on the page.
If you already uploaded a picture, you can also simply reference it with this markdown syntax:
To specify the image size, simply add the dimensions like this:
To shrink an image by a percentage amount, use this syntax:
To center-align an image, use this syntax:
{.align-center}
¶
Always insert images into an appropriate folder, and give them a specific name. The image should go in the same directory as the page you are creating. For example, an image for the page General>Physics>Astrodynamics>The Rocket Equation will go inside the asset folder General/Physics/Astrodynamics.
If you place the asset in the wrong location, a script will regularly move the asset to the correct location and modify your page to point to the correct image. Be mindful of this.
Don't let image sizes become too big (all images should be a .png format, especially diagrams). Ideally, most .png diagrams will be a few hundred kilobytes, and real-world images will be 1-2 megabytes. Keep all image sizes under 5 megabytes.
If possible, try to remove any white or blank backrounds, and leave a transparent backround. It will make the website look pretty! Here is an example of a duck png, where the background has been cropped:
Here are links to tutorials to cropping white backgrounds on images:
¶ Documents
Uploading documents is very similar to uploading images. Simply click the "assets" folder on the left toolbar and upload any file you want to link!
The syntax for referencing a document is similar to referencing an image - just remove the !:
[Ducks Ducks Ducks](/home/getting-started/tutorial-its-a-duck.png)
And a link to the document will be created:
Ducks Ducks Ducks
¶ Diagrams
You can make what are known as Mermaid diagrams using only text! This allows you to make flowcharts with ease, and without needing to draw one in separate software and upload it.
A tutorial to Mermaid diagrams is located here: https://mermaid-js.github.io/mermaid/#/flowchart?id=graph
An example of the syntax you would use to make a simple diagram is located here:
```mermaid
flowchart LR
A(Duck)
B(Sees Food)
C(Eats Food)
D(Gets Hungry)
A-.->B
B-->C
C--After a little while-->D
D--->B
```
And the resulting diagram: