Markdown is a lightweight markup language designed to be simple and easily readable by humans.
Writing and reading documents is a joy with Markdown's syntax, which is free of intrusive components.
Blog-Doc utilizes the Simple Markdown Editor for editing and previewing page and post content, and Marked for parsing that content.
Bellow are examples of common HTML tags written in Markdown and their output once parsed with Marked.
Headers
# H1
## H2
### H3
#### H4
##### H5
###### H6
<h1>H1</h1>
<h2>H2</h2>
<h3>H3</h3>
<h4>H4</h4>
<h5>H5</h5>
<h6>H6</h6>
Paragraphs
A paragraph is just plaintext! Awesome!
<p>A paragraph is just plaintext! Awesome!</p>
A paragraph is just plaintext! Awesome!
Line Breaks
I'm a paragraph, if you hit enter
and continue writing the content of the next line still belongs to me!
<p>I'm a paragraph, if you hit enter and continue writing, the content of the next line still belongs to me!</p>
I'm a paragraph, if you hit enter and continue writing, the content of the next line still belongs to me!
I'm a paragraph, if you hit enter twice
and continue writing, the content of the next line is a new paragraph!
<p>I'm a paragraph, if you hit enter twice</p>
<p>and continue writing, the content of the next line is a new paragraph!</p>
I'm a paragraph, if you hit enter twice
and continue writing, the content of the next line is a new paragraph!
I'm a paragraph, if you put at the end of a line two empty spaces
hit enter and continue writing,
the content of the next line still belongs to me
but with a break after each two empty spaces followed by an enter!
So all this text is one paragraph with multiple lines breaks!
And this lonely line is another paragraph!
And this paragraph
of multiple lines,
with only an enter
at the end of each line,
will output a single paragraph!
<p>
I'm a paragraph, if you put at the end of a line two empty spaces
<br />
hit enter and continue writing,
<br />
the content of the next line still belongs to me
<br />
but with a break after each two empty spaces followed by an enter!
<br />
So all this text is one paragraph with multiple lines breaks!
</p>
<p>And this lonely line is another paragraph!</p>
<p>And this paragraph of multiple lines, with only an enter at the end of each line, will output a single paragraph!</p>
I'm a paragraph, if you put at the end of a line two empty spaces
hit enter and continue writing,
the content of the next line still belongs to me
but with a break after each two empty spaces followed by an enter!
So all this text is one paragraph with multiple lines breaks!
And this lonely line is another paragraph!
And this paragraph of multiple lines, with only an enter at the end of each line, will output a single paragraph!
Emphasis
You can write in italic by surrounding your text with asterisks (*) or underscores (_).
This is a paragraph _with some italic text_ inside.
<p>
This is a paragraph
<em>with some italic text</em>
inside.
</p>
This is a paragraph with some italic text inside.
You can also write bold text by surrounding it with a double (**) or a double (__).
This is a paragraph **with some bold text** inside.
<p>
This is a paragraph
<strong>with some bold text</strong>
inside.
</p>
This is a paragraph with some bold text inside.
Blockquotes
To create a blockquote, add a greater than symbol > in front of a paragraph.
> Blog-Doc is the simplest Node.js CMS & SSG!
<blockquote>
<p>Blog-Doc is the simplest Node.js CMS & SSG!</p>
</blockquote>
Blog-Doc is the simplest Node.js CMS & SSG!
Lists
Markdown supports ordered (numbered) and unordered (bulleted) lists.
Creating lists with Markdown is a child's game!
To create an unordered list, you can use:
- hyphens `-`
- pluses `+`
- or asterisks `*`
<p>To create an unordered list, you can use:</p>
<ul>
<li>
hyphens
<code>-</code>
</li>
<li>
pluses
<code>+</code>
</li>
<li>
or asterisks
<code>*</code>
</li>
</ul>
To create an unordered list, you can use:
- hyphens
- - pluses
+ - or asterisks
*
To create an ordered list:
1. Just
2. Use
3. Numbers
<p>To create an ordered list:</p>
<ol>
<li>Just</li>
<li>Use</li>
<li>Numbers</li>
</ol>
To create an ordered list:
- Just
- Use
- Numbers
Links
Links in Markdown are composed of 3 parts:
- The link's text, delimited by [square brackets]
- The link's target, (Inside parentheses)
- An optional title for the link, "surrounded in quotes"
[Link text](https://example.com/ "Optional title")
<a href="https://example.com/" title="Optional title">Link text</a>
A link without the optional title:
[A link without the optional title](https://example.com/)
<a href="https://example.com/">A link without the optional title</a>
A link without the optional title
Links can also refer to a relative path, where the target is on the same domain.
The following examples will give you a better idea:
[Blog-Doc's documentation homepage](/)
[Install Blog-Doc](/docs/install-and-try-blog-doc)
<a href="/">Blog-Doc's documentation homepage</a>
<a href="/docs/install-and-try-blog-doc">Install Blog-Doc</a>
Blog-Doc's documentation homepage
Install Blog-Doc
On the same domain or not, the target can refer to a hash-link!
A hash-link is a link that redirects to a particular section in a page.
The target in this case contains the hash # of the section:
A hash-link to the "Headers" section on this page
[Headers in Markdown](#headers)
A hash-link to the "Use images" section in "Gallery"
[Using images in Blog-Doc](/docs/add-and-use-images-in-blog-doc#use-images)
A hash-link to a particular section on an external domain
[What is Markdown good for?](https://lebcit.github.io/posts/create-a-simple-markdown-based-blog-in-nodejs/#markdown)
<p>
A hash-link to the "Headers" section on this page
<br />
<a href="/docs/write-content-with-markdown-in-blog-doc#headers">Headers in Markdown</a>
</p>
<p>
A hash-link to the "Use images" section in "Gallery"
<br />
<a href="/docs/add-and-use-images-in-blog-doc#use-images">Using images in Blog-Doc</a>
</p>
<p>
A hash-link to a particular section on an external domain
<br />
<a href="https://lebcit.github.io/posts/create-a-simple-markdown-based-blog-in-nodejs/#markdown">
What is Markdown good for?
</a>
</p>
A hash-link to the "Headers" section on this page
Headers in Markdown
A hash-link to the "Use images" section in "Gallery"
Using images in Blog-Doc
A hash-link to a particular section on an external domain
What is Markdown good for?
A great feature of Markdown is the reference-style link.
Reference-style links simplify and organize your markup.
If you are referring multiple times to the same link in a document or just want to organize your links, then the reference-style link will become your best friend!
[Drafts] in Blog-Doc are used to save [Pages & Posts] for later use.
Blog-Doc's [Pages & Posts] can be saved as [Drafts] for later use.
You can choose to unpublish your [Pages & Posts] using [Drafts].
[Pages & Posts]: /docs/create-pages-and-posts-with-blog-doc
[Drafts]: /docs/create-pages-and-posts-with-blog-doc#drafts
<p>
<a href="/docs/create-pages-and-posts-with-blog-doc#drafts">Drafts</a>
in Blog-Doc are used to save
<a href="/docs/create-pages-and-posts-with-blog-doc">Pages & Posts</a>
for later use.
<br />
Blog-Doc's
<a href="/docs/create-pages-and-posts-with-blog-doc">Pages & Posts</a>
can be saved as
<a href="/docs/create-pages-and-posts-with-blog-doc#drafts">Drafts</a>
for later use.
<br />
You can choose to unpublish your
<a href="/docs/create-pages-and-posts-with-blog-doc">Pages & Posts</a>
using
<a href="/docs/create-pages-and-posts-with-blog-doc#drafts">Drafts</a>
.
</p>
Drafts in Blog-Doc are used to save Pages & Posts for later use.
Blog-Doc's Pages & Posts can be saved as Drafts for later use.
You can choose to unpublish your Pages & Posts using Drafts.
Images
Images in Markdown share almost the same syntax as links.
The only difference is that images' syntax begins with an exclamation mark !
Images in Markdown are composed of 4 parts:
- The exclamation mark
! - The image alternative text, delimited by [square brackets]
- The path to the image, (Inside parentheses)
- An optional title, "surrounded in quotes"
Let's see a real example:
<img
src="https://images.vici.org/crop/w175xh175/uploads/Baalbek_Temple_of_Bacchus.jpg"
alt="Temple of Bacchus in Baalbek, Lebanon"
/>
<img
src="https://images.vici.org/crop/w175xh175/uploads/Baalbek_Temple_of_Bacchus.jpg"
alt="Temple of Bacchus in Baalbek, Lebanon"
title="Temple of Bacchus"
/>
Maybe you guest it, maybe not, Markdown has a reference-style image too!
![Temple of Bacchus in Baalbek, Lebanon]
![Temple of Jupiter in Baalbek, Lebanon]
[Temple of Bacchus in Baalbek, Lebanon]: https://images.vici.org/crop/w175xh175/uploads/Baalbek_Temple_of_Bacchus.jpg
[Temple of Jupiter in Baalbek, Lebanon]: https://images.vici.org/crop/w175xh175/uploads/baalbek_t_jupiter_temple_08.jpg "Temple of Jupiter"
<img
src="https://images.vici.org/crop/w175xh175/uploads/Baalbek_Temple_of_Bacchus.jpg"
alt="Temple of Bacchus in Baalbek, Lebanon"
/>
<img
src="https://images.vici.org/crop/w175xh175/uploads/baalbek_t_jupiter_temple_08.jpg"
alt="Temple of Jupiter in Baalbek, Lebanon"
title="Temple of Jupiter"
/>
Linking images is also possible in Markdown.
To add a link to an image treat the whole image's syntax as the link's text.
The syntax looks like:
[](https://example.com/)
[](https://example.com/)
[](https://example.com/ "Optional title")
Let's see it in action:
[](https://live.staticflickr.com/7149/6842814197_2556b253a2_b.jpg)
[](https://live.staticflickr.com/7149/6842814197_2556b253a2_b.jpg)
[](https://live.staticflickr.com/7149/6842814197_2556b253a2_b.jpg "Temple of Bacchus")
<a href="https://live.staticflickr.com/7149/6842814197_2556b253a2_b.jpg">
<img src="https://images.vici.org/crop/w175xh175/uploads/Baalbek_Temple_of_Bacchus.jpg" alt="Temple of Bacchus in Baalbek, Lebanon" />
</a>
<a href="https://live.staticflickr.com/7149/6842814197_2556b253a2_b.jpg">
<img src="https://images.vici.org/crop/w175xh175/uploads/Baalbek_Temple_of_Bacchus.jpg" alt="Temple of Bacchus in Baalbek, Lebanon" title="Temple of Bacchus" />
</a>
<a href="https://live.staticflickr.com/7149/6842814197_2556b253a2_b.jpg" title="Temple of Bacchus">
<img src="https://images.vici.org/crop/w175xh175/uploads/Baalbek_Temple_of_Bacchus.jpg" alt="Temple of Bacchus in Baalbek, Lebanon" />
</a>
Code
To write inline code, surround your code with backticks ``
The `console` object has multiple methods in JavaScript!
<p>
The
<code>console</code>
object has multiple methods in JavaScript!
</p>
The console object has multiple methods in JavaScript!
To write a block of code, surround your block with a pair of 3 backticks ```.
```
p {
color: red;
}
```
<pre>
<code>
p {
color: red;
}
</code>
</pre>
p {
color: red;
}
Blog-Doc uses highlight.js to highlight block of code.
To highlight a block of code, provide the alias of the language for the block just after the first 3 backticks.
```js
console.log("Hello, World!")
```
<pre class="hljs">
<code class="language-js hljs language-javascript" data-highlighted="yes">
<span class="hljs-variable language_">console</span>
.
<span class="hljs-title function_">log</span>
(<span class="hljs-string">"Hello, World!"</span>)
</code>
</pre>
console.log("Hello, World!")
Visit the Supported Languages of highlight.js to get the correct alias if you're unsure.
Alternatively, you can write a block of code without providing an alias, highlight.js will automatically detect the language.
If the highlighter fails to detect the correct language for a block of code without an alias, just add the desired language to the block as indicated above.
Horizontal Rule
You can produce a horizontal rule tag <hr /> by placing three or more hyphens(-), asterisks(*), or underscores(_) on a line by themselves.
---
<hr />
Inline HTML
As John GRUBER, the creator of Markdown, says:
For any markup that is not covered by Markdown’s syntax, you simply use HTML itself.
So yes, you can use HTML in pages and posts!
I prefer to use `<br />` or just `<br>`<br />
instead of adding two empty spaces<br />
at the end of a line in a Markdown paragraph.
<p>
I prefer to use
<code><br /></code>
or just
<code><br></code>
<br />
instead of adding two empty spaces
<br />
at the end of a line in a Markdown paragraph.
</p>
I prefer to use <br /> or just <br>
instead of adding two empty spaces
at the end of a line in a Markdown paragraph.
Ids for Headers
This section refers to a special feature in LiteNode:
- Ids for H1 till H6 in Markdown!
As explained in the Links section, the target can be a hash-link.
So if you have an element with an id, you can use a hash-link to refer to this element.
Consider this simple HTML example:
<!-- A div with an id -->
<div id="my-div">
<p>Blog-Doc is the simplest Node.js CMS and SSG!</p>
</div>
<!-- Faraway from the div, in the same document -->
<!-- A hash-link targeting the `id` of the div -->
<a href="#my-div">What is Blog-Doc?</a>
Now, whenever a user clicks on the hash-link targeting the id of the div, the page jumps right away to this div, just like the above hash-link redirecting to the Links section.
In Markdown's syntax, there is no native way to add an id to an element.
Usually, hash-links are used on headers since the are at the top of a section.
Blog-Doc brings this option via a custom function, instead of loading additional modules, built with edge cases and typing typos in mind:
- Regex to match curly braces ignoring everything before the last hashtag
- Replace accented characters, by their non accented letter
- Replace upper case letters by lower case one
- Remove special characters except hyphen and underscore
- Replace any number of underscore by one hyphen
- Replace any number of space by one hyphen
- Remove any number of hyphen at the beginning
- Replace any number of hyphen by one hyphen only
- Remove any number of hyphen at the end
To add an id, add a curly braces with a hashtag followed by the id's text.
The following examples will give you a better idea:
<!-- Heading tags with an id property -->
## My awesome H2 title {# my-awesome-h2-title}
<h2 id="my-awesome-h2-title">My awesome H2 title</h2>
### My awesome H3 title {# my awesome h3 title}
<h3 id="my-awesome-h3-title">My awesome H3 title</h3>
#### My awesome H4 title {# My awesome H4 title}
<h4 id="my-awesome-h4-title">My awesome H4 title</h4>
Every Whitespace is automatically replaced by a hyphen and any number of consecutive hyphens are replaced by one hyphen only.
Any number of hyphen at the beginning or the end of the id's text are removed so the following is also valid:
## My awesome H2 title { # ----- My ----- aWEsOMe ----- h2 ----- tITlE ----- }
Whatever the number of whitespace characters / hyphens is at the beginning, between the words or at the end, the HTML output will still be:
<h2 id="my-awesome-h2-title">My awesome H2 title</h2>
Anything before the last hashtag # is ignored and special characters in the id's text are ignored too:
## My awesome H2 title { /!@# a comment ?%^& # -my= awesome+ h2 \ ( title ) | }
The HTML output will be:
<h2 id="my-awesome-h2-title">My awesome H2 title</h2>
At build time, predefined ids will be generated into the HTML of the static site.
Nota Bene
As you have seen, using Markdown to write your content is way easier than using HTML to do it.
Keep in mind that you can use HTML in the content of your pages and posts.
Wishing you an enjoyable writing with Markdown in Blog-Doc!