This is a tutorial to Markdown written in Markdown:) Btw Jianshu is a nice platform to try and use Markdown!
Introduction
Markdown (.md) is a lightweight markup language with plain text formatting syntax designed so that it can be converted to HTML and many other formats using a tool by the same name.
Markdown Syntax
Heading
There are five common header levels.
# Head 1
Head 1
## head 2
head 2
### head 3
head 3
Text attributes
*italic*, **bold**, `monospace`
italic, bold, monospace
Escape
Use \ to escape markdown characters like \*, \-, \*\*
Use \ to escape markdown characters like *, -, **
Reference
A [link to Markdown Wikipedia](https://en.wikipedia.org/wiki/Markdown).
For external files like images you want to reference in a Markdown file, sometimes it's better to find a image bed to store in case of outdated (broken) links.
You may find it inconvenient to use absolute paths to reference external files, especially when you upload markdown documents from local to GitLab, or change your directory structure. So relative path may be a better choice.
Paragraph
Paragraphs are separated
by a blank line.
Paragraphs are separated
by a blank line.
List
Bullet list:
- apples
- green apples
- oranges
- pears
Numbered list:
1. apples
2. oranges
3. pears
Bullet list:
- apples
- green apples
- oranges
- pears
Numbered list:
- apples
- oranges
- pears
Quote
> Quote 1
> Quote 2
Quote 1
Quote 2
Code Highlight
```python # Gitlab's extended syntax allow you to specify the highlight language here
(code here)
```
def function():
#indenting works just fine in the fenced code block
s = "Python syntax highlighting"
print s
Table
|hello|markdown|world|
|---|---|---|
|1|3.14|**1024**|
|2|*6.28*|2048|
| hello | markdown | world |
|---|---|---|
| 1 | 3.14 | 1024 |
| 2 | 6.28 | 2048 |
Writing Markdown
As markdown uses plain text formatting syntax, you can create a .md file and write in any kind of test editor, including GitLab itself:
For those who demand a better offline writing experience, I recommend an open-source eidtor application called Atom. It supports code (including Markdown) highlighting and Markdown Preview (Ctrl + Shift + M):
Watch out: Atom uses its own render, so you may not get the exact format as GitLab in Atom's previewer. You can adjust Atom's markdown to Github style (more compatible with GitLab) following this:
- Edit > Preferences (Linux), Atom > Preferences (macOS), or File > Preferences (Windows)
- Find
markdown-previewin Packages - settings > use GitHub.com style
Convert Markdown to PDF
There are different ways to convert Markdown to PDF. Some are easier to use while others have more beautiful format. Here we only introduce one easy way with Atom. First we need install a markdown-themeable-pdf package:
- Open Panel:
Ctrl+Shift+P - Settings View: Install Packages And Themes
- Search and install
markdown-themeable-pdf
Then we only need to use Ctrl + Shift + E to convert Markdown. The PDF file would be in the same directory as the Markdown document. You can also install pdf-view package to allow reading PDF in Atom.
Watch out: if you reference files (excluding images) in the Markdown document files, you should make sure your paths have corresponding accessible sources.
Use Markdown on Gitlab
Is syntax the same?
GitLab (https://about.gitlab.com/) implements an extended markdown language, so there are some slight differences you may come across between standard syntax and GitLab Syntax, like code highlight and tables. For more details, please refer to GitLab's markdown help. GitLab can automatically render uploaded markdown files (.md).
How does it look?
On Gitlab, you'll see rendered Markdown documents directly. You can also check the plain text of your Markdown document on Gitlab (Raw mode):
Can I sync my markdown files?
You can use GitLab to maintain codes, markdown documents and other external files. As Gitlab uses Git to do version control of all files, it can keep all the historical versions of your documents. You can easily access any of them on Gitlab.
Gitlab allows us to edit and save files on its web page directly, but cannot upload / update a whole folder with one click. So if you want to edit your files and folders on your local machine, then sync to our GitLab document library, you should operate as following:
- For non-technical users, use Sourcetree or other similar GUI application to interact with Gitlab's Git repo
- For technical users, just use Git to do this (need to set SSH key or HTTP's id/password).
Some Advices
- Markdown is more suitable for situations that do not need too complex format. For example, if you want to create a table sheet for a survey, you'd better use Microsoft Word. You can also try to create a table with Markdown, and copy the formatted table to Word for further editing.
