Discover the extended Markdown syntax used on this tech blog, generated from the template πŸ§ͺ Jekyll Tech blog, to write articles or to generate static web pages. It is based on Kramdown syntax with GFM parser and a light custom extension for rendering. Besides, this article is written with this syntax. At the top of the web page, click on Source to explore its source code and on Table of contents to browse the supported features. So, you can mix this syntax with existing macro and native HTML syntaxes to write any content. As this blog is highly configurable, you can build your custom macros. Each article also has metadata to inject constants of configurations.

Summary of supported features by the extended Markdown syntax

Read the documentation of the Kramdown syntax. All contents, even if unavailable with the extended Markdown syntax, can be shown thanks to embedded native content: HTML, JS, CSS, or macros: includes and tags of the Liquid template.

Feature name Comment Extended Markdown syntax Existing Macro syntax Native HTML syntax
Structure
Heading Organize your content with part, subpart, sub-subpart, etc. βœ… ❌ βœ…
New line & Paragraph Organize the content in a part βœ… ❌ βœ…
Horizontal Rule Break between paragraph-level elements βœ… ❌ βœ…
Note Soon refactored! Add your notes: info, question, warning, error, success, etc. ❌ ❌ βœ…
Textual Content
Enchanced Text Enhance your text: italics, bold, strikethrough, inline code, highlight, superscript, subscript, etc. βœ… ❌ βœ…
Link Use absolute and relative links named or not and re-usable βœ… ❌ βœ…
Emoticon Use emoticons with shortcode or unicode βœ… ❌ βœ…
List Build an ordered, unordered, definition or task lists and sublists βœ… ❌ βœ…
Table Arrange the content in rows and columns with an optional header. βœ… ❌ βœ…
Blockquote Format a special sentence of paragraph to draw attention to the reader βœ… ❌ βœ…
Quote Soon refactored! Quote your authors βœ… ❌ βœ…
Footnote Put extra information at the bottom of the article referencing inside content βœ… ❌ βœ…
Abbreviation Shorten used word or concept by keeping the accessible meaning βœ… ❌ βœ…
Illustration Content
Image Soon documented! βœ… βœ… βœ…
Video Soon documented! ❌ βœ… βœ…
Presentation Soon documented! ❌ βœ… βœ…
Diagram Soon documented! ❌ βœ… βœ…
Informatics Code
Programming Language Highlight code: python, java, scala, rust, c#, c++, c, bash, ruby, go, typescript, javascript, html, css ... βœ… ❌ βœ…
Terminal Highlight content in a terminal βœ… ❌ βœ…
Text File Highlight text content: plain, json, yaml, xml, ini ... βœ… ❌ βœ…
Mathematics Equation
In-Line Equation Use LateX syntax for in-line equation βœ… ❌ βœ…
Single-Line Equation Use LateX syntax for single-line equation βœ… ❌ βœ…
Multi-lines Equation Use LateX syntax for multi-lines equation βœ… ❌ βœ…
Special Content
HTML Put native HTML when the Markdown syntax is not available, it can contain Markdown in its markups ❌ ❌ βœ…
Comment Comment content ❌ ❌ βœ…
Escape Escape meta or special characters βœ… ❌ βœ…
Others Create your macros, extend the project or the tools everything is open-source ❌ ❌ βœ…

What is the Markdown syntax? It is a lightweight and popular text metalanguage that is a writing standard. It is often converted into HTML, allowing it to be easily shared on the web :spider_web:. After converting to HTML, it is decorated and animated by CSS style sheets and/or JS scripts. See more details on this Markdown Guide.

Why use Markdown? Because it is very handy to use for the reader and the writer:

  • Reader: The generated HTML content from the Markdown content is compatible with all web browsers that can render it for the final reader.
  • Writer: The Markdown content continues to be separated from the rendering. In addition, it is easy to learn and use syntax, with the pros of portability and compatibility, flexibility and customizable, and readability and maintainability. Modify its article so the content is more human-writable/readable and shorter than the HTML code, less expressive, but sufficient for a blog post.

Why use an extended Markdown syntax? Markdown has a basic syntax, that is limited for more advanced use cases (like tables, code blocks, syntax highlighting, footnotes and so one…). This extension is Markdown compatible, so all articles written in Markdown can be used directly in this blog without breaking changes, and largely used by an active community.

How it works? The files having the Markdown extension .md or .markdown are processed to HTML with this processing workflow:

Extended Markdown to HTML
Extended Markdown to HTML

The following sections give examples for each usage to create your content with the right syntax.

Structure

Heading

Make a part, a subpart, and a sub-subpart.

It is used for each section here.

Source code:

# H1
## H2
### H3


H1
======

H2
------

New line & Paragraph

Let 2 trailing spaces have an end of the line, and let an empty line for a new paragraph:

Hello,

World!

Source code:

Hello,␣␣\n
\n
World!\n

Note: \n and ␣ represent respectively a new line character and a space character.

Horizontal rule

To create a horizontal rule, use three or more asterisks ***, dashes ---, or underscores ___ on a line by themselves:


Source code:

---

Note

Add your notes: info, question, warning, error, and success etc.

INFO

Source code:

<div class="info">
INFO
</div>
QUESTION

Source code:

<div class="question">
QUESTION
</div>
WARNING

Source code:

<div class="warning">
WARNING
</div>
ERROR

Source code:

<div class="error">
ERROR
</div>
SUCCESS

Source code:

<div class="success">
SUCCESS
</div>

Textual Content

Enchanced Text

Enhance your text:

  • Italics: italics or italics
  • Bold: bold or bold
  • Strikethrough: strikethrough
  • Bold & Italics: bold italics or bold italics
  • Inline code: code
  • Highlight: highlight
  • Supscript: supsup
  • Subscript: subsub

Source code:

- Italics: *italics* or _italics_  
- Bold:	**bold** or __bold__ 
- Strikethrough: ~~strikethrough~~
- Bold & Italics: **_bold italics_** or __*bold italics*__
- Inline code: `code`
- Highlight: <mark>highlight</mark>
- Supscript: sup<sup>sup</sup>
- Subscript: sub<sub>sub</sub>

It works with absolute and relative links:

Simple Link

https://www.glegoux.com

Source code:

<https://www.glegoux.com>

Named Link

glegoux

Source code:

[glegoux](https://www.glegoux.com)

with a title:

glegoux1 (with the title glegoux's Homepage)

Source code:

[glegoux](https://www.glegoux.com "glegoux's Homepage")

Reference-style Link

You can use shortcuts for your links to use that several times on the article or to centralize links:

glegoux1 glegoux2

Source code:

[glegoux1][1] [glegoux2][1]

[1]: https://www.glegoux.com "glegoux's Homepage"

Emoticon

Use emoji, with gemoji see emoji cheat sheet.

For example: with shortcode :smile: :scream: :yum: or unicode directly πŸ˜€ 😱 πŸ˜‹.

Source code for emoji with shortcode:

:smile: :scream: :yum:

Source code for emoji with unicode:

πŸ˜€ 😱 πŸ˜‹

List

Ordered List

  1. item
  2. item
  3. item

Source code:

1. item
2. item
3. item

Use +, * and - indifferently.

Unordered List

  • item
    • subitem
    • …
  • item
    • subitem
    • …
  • item

Source code:

 * item
 * item
 * item

Definition List

item
definition
item
definition

Source code:

item
: definition

item
: definition

Task List

  • item
  • item
  • item

Source code:

- [x] item
- [x] item
- [ ] item

Table

TODO

Blockquote

TODO

Quote

Quote authors:

Talk is cheap. Show me the code.

Linus Torvalds, creator of the Linux operating system

Source code:

> Talk is cheap. Show me the code.

Linus Torvalds, creator of the Linux operating system

Footnote

Footnotes work mostly like reference-style links. A footnote is made of two things: a marker in the text that will become a superscript number; a footnote definition that will be placed in a list of footnotes at the end of the document. A footnote looks like this:

That’s some text with a footnote1.

Source code:

That's some text with a footnote.[^1]

[^1]: And that's the footnote.

Abbreviation

The HTML specification is maintained by the W3C.

Source code:

The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language

Illustration Content

Image

TODO

Video

TODO

Presentation

TODO

Diagram

TODO

Informatics Code

Programming Language

The used syntax highlighter is Rouge, see the list of supported languages and lexers, with python, java, scala, rust, c#, c++, c, bash, ruby, go, typescript, javascript, html, css etc.

print("Hello world!")

Source code:

~~~ python
print("Hello world!")
~~~
print("Hello World!", quote = FALSE)

Source code:

~~~ r
print("Hello World!", quote = FALSE)
~~~
disp('Hello World!')

Source code:

~~~ m
disp('Hello World!')
~~~
System.out.println("Hello world!");

Source code:

~~~ java 
System.out.println("Hello world!");
~~~
println("Hello world!")

Source code:

~~~ kotlin 
println("Hello world!")
~~~
println("Hello world!")

Source code:

~~~ scala 
println("Hello world!")
~~~
Console.WriteLine("Hello world!");

Source code:

~~~ csharp 
Console.WriteLine("Hello world!");
~~~
print("Hello World!");

Source code:

~~~ dart
print("Hello World!");
~~~
print("Hello World!")

Source code:

~~~ swift
print("Hello World!")
~~~
println!("Hello World!");

Source code:

~~~ rust
println!("Hello World!");
~~~
std::cout << "Hello World!";

Source code:

~~~ c++
std::cout << "Hello World!";
~~~
printf("Hello, World!");

Source code:

~~~ c 
printf("Hello, World!");
~~~
echo "Hello world!"

Source code:

~~~ bash 
echo "Hello world!"
~~~
puts "Hello world!"

Source code:

~~~ ruby 
puts "Hello world!"
~~~
import("fmt")

fmt.Println("Hello world!")

Source code:

~~~ go
import("fmt")

fmt.Println("Hello world!")
~~~
print "Hello world!";

Source code:

~~~ php
print "Hello world!";
~~~
print "Hello world!";

Source code:

~~~ perl
print "Hello world!";
~~~
console.log("Hello world!");

Source code:

~~~ typescript
console.log("Hello world!");
~~~
console.log("Hello world!");

Source code:

~~~ javascript
console.log("Hello world!");
~~~
CREATE TABLE helloworld;

Source code:

~~~ sql
CREATE TABLE helloworld;
~~~
<p>Hello world!</p>

Source code:

~~~ html
<p>Hello world</p>
~~~
.hello .world {
  text-align: center
}

Source code:

~~~ css
.hello .world {
  text-align: center
}
~~~
.hello {
  .world {
    text-align: center
  }
}

Source code:

~~~ sass
.hello {
  .world {
    text-align: center
  }
}
~~~

Terminal

Have a dark terminal container:

$ command
result

Source code:

~~~ terminal
$ command
result
~~~

Text File

Highlight your text file content: plain, json, yaml, xml, ini etc.

"Hello World!"

Source code:

~~~
"Hello World!"
~~~
{"message": "Hello World!"}

Source code:

~~~ json
{"message": "Hello World!"}
~~~
hello:
  world: "Hello World!"

Source code:

~~~ yaml
hello:
  world: "Hello World!"
~~~
<?xml version="1.0" encoding="UTF-8"?>
<message>Hello World!</message>

Source code:

~~~ xml
<?xml version="1.0" encoding="UTF-8"?>
<message>Hello World!</message>
~~~
[message]
message="Hello World!"

Source code:

~~~ ini
[message]
message="Hello World!"
~~~

Mathematics Equation

Use LateX syntax, see latex-project.org.

The dollar symbol $ becomes a meta symbol, so there is a conflict with the dollar symbol use the HTML code &#36; to see the dollar symbol $.

In-line Equation

This equation $\int_0^1 x^2dx = \frac{1}{3}$ is in-line.

Source code:

This equation $\int_0^1 x^2dx = \frac{1}{3}$ is in-line.

Single-line Equation

This equation is single-line and centered:

\[\int_0^1 x^2dx = \frac{1}{3}\]

Source code:

$$\int_0^1 x^2dx = \frac{1}{3}$$

Multi-lines Equation

This equation is multi-line and centered:

\[\displaylines{ \int_0^1 x\,dx = \frac{1}{2} \\ \int_0^1 x^2dx = \frac{1}{3} }\]

Source code:

$$
\displaylines{
\int_0^1 x\,dx = \frac{1}{2} \\
\int_0^1 x^2dx = \frac{1}{3} 
}
$$

Special Content

HTML

TODO

Comment

If you want to put a hidden text not displayed in the article but present in the written source, that is to say, a comment, simply do an HTML comment:

Source code:

<!-- comments -->

Escape

All described multi-lines escapes can work to escape inline and single line characters.

Character by Character

Use a backslash \, see the list of all the characters that can be escaped, or HTML entities like &lt; or &gt;.

Inline and Single Line Characters

Instead of using multiple backslashes, use for multiple characters inline and composing a single line, these syntaxes:

  • `inline or single line`

But you cannot display ` inside a section delimited by `.

Multi-lines Characters

  • <code>inline or single line</code>

If you have to display reserved characters such as <, and > within the <code> section, the characters must be escaped using their respective HTML entity: <: &lt;, and >: &gt;. But you cannot escape &.

  • <pre>multi-lines</pre>

If you have to display reserved characters such as <,>, &, and " within the <pre> section, the characters must be escaped using their respective HTML entity: <: &lt;, >: &gt;, &: &amp;, and ": &quot;.

  • ~~~ multi-lines ~~~

But you cannot to display reserved sequence of characters ~~~ within a section delimited by ~~~.

  • ``` multi-lines ```

But you cannot to display reserved sequence of characters ``` within a section delimited by ```.

Others

TODO

  1. And that’s the footnote. ↩


Also read
Comments