Overview of Markdown#
Purpose#
Markdown is a lightweight markup language created by John Gruber. It allows people to write documents in an easy-to-read and easy-to-write plain text format, which can then be converted into valid XHTML (or HTML) documents.
Readability is, above all, the most important aspect. A document written in Markdown format should be able to be published directly as plain text and should not look like it is made up of many tags or formatting instructions. The Markdown syntax is influenced by several existing text-to-HTML formats, including Setext, atx, Textile, reStructuredText, Grutatext, and EtText, with the greatest inspiration actually coming from the format of plain text emails.
In summary, the syntax of Markdown consists of a few carefully selected symbols, whose functions are clear at a glance. For example: adding asterisks on either side of text makes it look like emphasis. Markdown lists look, well, like lists. Markdown block quotes really look like quoted text, just like you’ve seen in emails.
Compatibility with HTML#
The goal of Markdown syntax is to become a writing language suitable for the web.
Markdown does not aim to replace HTML, nor does it seek to be close to it; its syntax is minimal and corresponds to only a small subset of HTML tags. The idea behind Markdown is not to make HTML documents easier to write. In my view, HTML is already easy to write. The philosophy of Markdown is to make documents easier to read, write, and modify freely. HTML is a publishing format, while Markdown is a writing format. Thus, the syntax of Markdown only covers the range that plain text can encompass.
Tags not covered by Markdown can be written directly in HTML within the document. There is no need to annotate whether it is HTML or Markdown; just add the tags directly.
The only restrictions apply to some HTML block elements—such as <div>, <table>, <pre>, <p>—which must be separated from other content by empty lines before and after, and their start and end tags must not be indented with tabs or spaces. Markdown generators are smart enough not to add unnecessary <p> tags outside of HTML block tags.
An example is as follows, adding an HTML table in a Markdown file:
This is a regular paragraph.
<table>
<tr>
<td>Foo</td>
</tr>
</table>
This is another regular paragraph.
Please note that Markdown formatting syntax will not be processed between HTML block tags. For example, using Markdown-style emphasis within an HTML block will have no effect.
Inline HTML tags such as <span>, <cite>, <del> can be used freely within Markdown paragraphs, lists, or headings. Depending on personal preference, one can even choose to use HTML tags directly for formatting instead of Markdown formatting. For example, if you prefer HTML's <a> or <img> tags, you can use those directly without using the link or image tag syntax provided by Markdown.
Unlike being between HTML block tags, Markdown syntax is valid between HTML inline tags.
Basic Markdown Syntax#
Code Blocks#
If you only want to highlight a function name or keyword in a statement, you can use `function_name()`.
Typically, editors adapt suitable highlighting methods based on code snippets, but you can also wrap a piece of code with ``` and specify a language.
Supported languages: actionscript, apache, bash, clojure, cmake, coffeescript, cpp, cs, css, d, delphi, django, erlang, go, haskell, html, http, ini, java, javascript, json, lisp, lua, matlab, nginx, objectivec, perl, php, python, r, ruby, scala, smalltalk, sql, tex, vbscript, xml
{% raw %}
``` javascript
$(document).ready(function () {
alert('hello world');
});
```
{% endraw %}
Thanks to hexo vortex for the help!
See hexo tag plugins
You can also use 4 spaces for indentation and paste the code to achieve the same effect.
Headings#
Markdown provides two ways (Setext and Atx) to display headings.
Example:
Setext style
Heading 1
=================
Heading 2
-----------------
Atx style
# Heading 1
## Heading 2
###### Heading 6
Line Breaks#
Use two or more spaces at the end of a line to indicate a line break.
Blockquotes#
Use [greater-than sign + space] at the beginning of a line to indicate a quoted paragraph, which can nest multiple quotes.
Syntax:
> This is a quote,
> there is no line break here,
> and here it breaks.
> > Nested inside
Effect:
This is a quote,
there is no line break here,
and here it breaks.Nested inside
Lists#
- Unordered lists use *, +, or - followed by a space to indicate.
Syntax:
* Item 1
* Item 2
* Item 3
+ Item 1
+ Item 2
+ Item 3
- Item 1
- Item 2
- Item 3
Effect:
- Item 1
- Item 2
- Item 3
- Item 1
- Item 2
- Item 3
-
Item 1
-
Item 2
-
Item 3
-
Ordered lists use numbers followed by a period and a space.
Syntax:
1. Use [number + space] before the list
2. We will automatically add numbers for you
7. Don’t worry about incorrect numbers; when displayed, we will automatically correct this line's 7 to 3
Effect:
- Use [number + space] before the list
- We will automatically add numbers for you
- Don’t worry about incorrect numbers; when displayed, we will automatically correct this line's 7 to 3
Emphasis#
Markdown uses * or _ to indicate emphasis.
Syntax:
Single asterisk = *italic*
Single underscore = _italic_
Double asterisks = **bold**
Double underscores = __bold__
Strikethrough = ~~bold~~
Effect:
Single asterisk = italic
Single underscore = italic
Double asterisks = bold
Double underscores = bold
Strikethrough = bold
Tables#
Syntax:
| Tables | Are | Cool |
| ------------- |:-------------:| -----:|
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |
or
dog | bird | cat
----|------|----
foo | foo | foo
bar | bar | bar
baz | baz | baz
Effect:
| Tables | Are | Cool |
|---|---|---|
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |
or
| dog | bird | cat |
|---|---|---|
| foo | foo | foo |
| bar | bar | bar |
| baz | baz | baz |
Links#
Markdown supports two styles of links: Inline and Reference.
Inline: The link text marked with square brackets is immediately followed by the link enclosed in parentheses. If the link has a title attribute, it is added in the link with a space plus "title attribute".
Reference: Generally used when the same link is used in multiple different places. It typically consists of two parts: the calling part is [link text][ref]; the defining part can appear elsewhere in the text, formatted as [ref]: http://some/link/address (optional title).
Note: The ref is case-insensitive.
Syntax:
This is an Inline [example](http://sphenginx.github.io "optional title").
This is a Reference [example][ref].
[ref]: http://sphenginx.github.io (optional title)
Effect:
This is an Inline example.
This is a Reference [example][ref].
[ref]: http://sphenginx.github.io (optional title)
Images#
The usage of images is basically similar to links, just add an exclamation mark before the square brackets.
Syntax:
Effect:
Note: Markdown cannot set image sizes; if you must set them, you should use HTML tags <img>.
<img src="https://avatars1.githubusercontent.com/u/1829395?v=3&s=460" width="400" height="100">
Effect is as follows:
Horizontal Lines#
Use three or more *, - or _ in a line to add a horizontal line, which can have spaces but no other characters.
Syntax:
***
Effect:
Escape Characters#
The escape character in Markdown is , which can escape:
\\ backslash
\` backtick
\* asterisk
\_ underscore
\{\} curly braces
\[\] square brackets
\(\) parentheses
\# hash
\+ plus
\- minus
\. period
\! exclamation mark
Colors and Fonts#
Markdown does not support colors and fonts, so if you want to add colors or fonts, you can only use HTML tags to achieve these needs.
Syntax:
<font color="red">I am red</font>
Effect:
I am red
Advanced Techniques#
Creating a To-Do List#
Syntax:
- [ ] Support exporting documents in PDF format
- [ ] Improve Cmd rendering algorithm, using local rendering techniques to enhance rendering efficiency
- [x] Added To-Do list feature
- [x] Fixed LaTex formula rendering issue
- [x] Added LaTex formula numbering feature
Effect:
- Support exporting documents in PDF format
- Improve Cmd rendering algorithm, using local rendering techniques to enhance rendering efficiency
- Added To-Do list feature
- Fixed LaTex formula rendering issue
- Added LaTex formula numbering feature
Efficiently Drawing Flowcharts | Sequence Diagrams#
For some reason, Git pages do not support this syntax; you can copy it into the latest Markdown syntax parser to try, or click Markdown Online Editor to try.
st=>start: Start
op=>operation: Your Operation
cond=>condition: Yes or No?
e=>end
st->op->cond
cond(yes)->e
cond(no)->op
Inline HTML Elements#
Currently, only some inline HTML elements are supported, including <kdb> <b> <i> <em> <sup> <sub> <br>, such as
- Key Display
Use <kbd>Ctrl<kbd>+<kbd>Alt<kbd>+<kbd>Del<kbd> to restart the computer
Effect:
Use Ctrl+Alt+Del to restart the computer
- Code Blocks
Using <pre></pre> elements can also form code blocks
- Bold Italics
<b> Markdown is also applicable here, such as *bold* </b>
Extensions#
Supports jsfiddle, gist, runjs, Youku videos; just fill in the URL, and a preview will be automatically added after it, which will expand related content when clicked.
http://{url_of_the_fiddle}/embedded/[{tabs}/[{style}]]/
https://gist.github.com/{gist_id}
http://runjs.cn/detail/{id}
http://v.youku.com/v_show/id_{video_id}.html
Formulas#
When you need to insert mathematical formulas in the editor, you can use two dollar signs $$ to wrap TeX or LaTeX formatted mathematical formulas. After submission, the Q&A and article pages will load Mathjax as needed to render the mathematical formulas. For example:
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a}. $$
$$
x \href{why-equal.html}{=} y^2 + 1
$$
Effect is as follows:
Markdown Editors#
Windows Platform
- MarkdownPad
- Haroopad - The next document processor
After entering the homepage, click on the user to enter the download interface.
Linux Platform
Mac Platform
Conclusion#
The above formats are relatively common, so we have provided detailed explanations for these syntaxes. Besides these, Markdown has other syntaxes; if you want to learn more, you can refer to this “Markdown Syntax Explanation”. 😄 (It seems hexo does not support emoji)……
Appendix#
I strongly recommend that you write an article using Markdown right now to experience the elegance of Markdown!