Getting started

Mon, 01 Jan 2024 00:00:00 +0000

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

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: sup^sup
Subscript: sub_sub

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>

Link

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

item
item
item

Source code:

item
item
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 footnote¹.

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 $ 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 < or >.

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: <: <, and >: >. 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: <: <, >: >, &: &, and ": ".

~~~ 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

And that’s the footnote. ↩

Software Engineering Blog - Bob

My First Blog Post

:bulb: Introduction

:rocket: Part 1

👀 Read more

Getting started

Structure

Heading

New line & Paragraph

Horizontal rule

Note

Textual Content

Enchanced Text

Link

Emoticon

List

Table

Blockquote

Quote

Footnote

Abbreviation

Illustration Content

Image

Video

Presentation

Diagram

Informatics Code

Programming Language

Terminal

Text File

Mathematics Equation

In-line Equation

Single-line Equation

Multi-lines Equation

Special Content

HTML

Comment

Escape

Others