1. For generated page.excerpt, include the first paragraphs and/or avoid using comments after the front matter.

2. If using the inline attribute list {: ... } and it doesn’t work as expected, see further Attribute List Definitions.

Basic Features

Headings

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Paragraphs

Elit ex ex eiusmod duis cupidatat duis esse laboris et sit reprehenderit eu. Elit sint nostrud ex reprehenderit fugiat do elit anim veniam nulla veniam amet. Nisi velit deserunt sunt excepteur irure ut ipsum excepteur minim.

Et laborum minim elit laboris dolor in. Nisi sunt labore pariatur magna fugiat cupidatat qui quis consequat aliqua commodo. Dolor nisi veniam elit proident. Irure laboris tempor consectetur ad enim ea officia ullamco.

Emphasis

Bold text

Italicized text

Strikethrough

Lists

Ordered List

1. First item
2. Second item
3. Third item
   1. Indented item
   2. Indented item
4. Fourth item

Unordered List

• First item
• Second item
• Third item
  • Indented item
    • Indented item
• Fourth item

Definition List

First Term

This is the definition of the first term.

Second Term

This is one definition of the second term.

This is another definition of the second term.

Task/Todo List

• Write the press release
• Update the website
• Contact the media

Links

https://jekyllrb.com

Free Palestine.

Blockquotes

Words can be like X-rays, if you use them properly—they’ll go through anything. You read and you’re pierced.

—Aldous Huxley, Brave New World

Codes

Sample output: This is sample output from a computer program.

Keyboard input: Ctrl + Shift + Esc

Inline code: {"firstName": "John","lastName": "Smith","age": 25}

Block code:

1
2
3
4
5
{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}

Footnotes

Here’s a simple footnote,¹ and here’s a longer one.²

Tables

Table with Github Flavored Markdown:

Table with HTML elements:

Horizontal Rule

Images

Float to left

Labore do pariatur labore labore Lorem occaecat nulla. Non do adipisicing est officia et. Dolore ullamco laboris est commodo laborum magna ut amet ad dolor ipsum anim aliquip consectetur. Cupidatat culpa in quis ea quis dolor amet velit minim.

Float to right

Enim voluptate ullamco amet ipsum qui incididunt aliqua culpa cillum commodo aliqua. Incididunt Lorem consequat elit tempor officia sunt incididunt Lorem nulla minim excepteur duis consequat. Ullamco eiusmod ex consectetur fugiat dolore laboris nulla dolor. Consequat esse cupidatat sunt sit proident consequat officia sit. In enim ea tempor laborum. Dolor laboris esse ad consectetur minim ut velit non ipsum minim labore.

Extended Features

Code Blocks

This is a code block with syntax highlighting:

1
2
3
4
5
6
{
  "thisSyntax": error,
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}

For more syntax highlighting see: Rouge Highlighting

Admonitions

Alerts or admonitions are frequently used in documentation to draw attention to warnings, notes, and other important information. The example below is adapted from GitHub Flavored Markdown.

Default:

General information or also for Blockquote alternatives.

Note:

Highlights information that users should consider, even when skimming.

Tip:

Optional information to help a user be more successful.

Important:

Crucial information necessary for users to succeed.

Warning:

Critical content requiring immediate user attention due to potential risks.

Caution:

Potential negative consequences of an action.

Diagramming

Diagramming and charting powered by Mermaid:

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
    commit

For more Mermaid syntax see: Mermaid Diagram

Mathematics

inline: \(f(x) = \int_{-\infty}^\infty \hat f(\xi)\,e^{2 \pi i \xi x} \,d\xi\)

display mode (centered):

Other elements

Abbreviation: *[HTML]: Hyper Text Markup Language The HTML specification is maintained by the W3C.

Marked: very important words.

Subscript: C₈H₁₀N₄O₂

Superscript: E=mc².

Emoji Shortcodes

If you see :raised_hand: as an emoji like this ✋ it means Emoji Shortcode is enable by plugin, otherwise open terminal and run the command below:

1
2
3
4
5
6
7
8
# Add plugin to Gemfile
echo 'gem "jemoji", group:jekyll_plugins' >> Gemfile

# Install plugin
bundle install

# Test on local
bundle exec jekyll serve --watch

In most cases, you can simply copy an emoji from a source like Emojipedia or EmojiCopy then paste it into your document.

Introduction

Here’s a refined and detailed explanation of the different types of diagrams you can create with Mermaid.js, including the syntax used for each Each type of Mermaid diagram is designed to fulfill specific needs in documentation and programming, providing an intuitive way to visualize complex information through simple text descriptions:

Flowchart

Flowcharts are used to represent process flows or workflows. They show the sequence of steps in a process, helping to visualize the order and connections between tasks.

flowchart TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[fa:fa-car Car]

• flowchart TD specifies a top-down layout.
• Arrows (-->) indicate the direction of flow.
• |Get money| represents the label on the arrow.

Gantt Chart

Gantt charts are used for project planning, displaying timelines and the progress of various tasks over time.

gantt
    title A Gantt Diagram
    dateFormat  YYYY-MM-DD
    section Section
    A task           :a1, 2014-01-01, 30d
    Another task     :after a1  , 20d
    section Another
    Task in sec      :2014-01-12  , 12d
    another task      : 24d

• gantt denotes the chart type.
• dateFormat sets the date format.
• section groups tasks into sections.
• Tasks are defined with a start date and duration.

Class Diagram

Class diagrams represent the structure of classes in object-oriented programming, showing their attributes and methods.

classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
      +String beakColor
      +swim()
      +quack()
    }
    class Fish{
      -int sizeInFeet
      -canEat()
    }
    class Zebra{
      +bool is_wild
      +run()
    }

• classDiagram specifies the diagram type.
• Animal <|-- Duck shows inheritance.
• Classes and their attributes/methods are defined within class blocks.

State Diagram

State diagrams represent states and transitions of an entity, useful for modeling state changes in a system.

stateDiagram-v2
    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]

• stateDiagram-v2 indicates the version.
• [*] represents the initial and final states.
• Transitions are shown with arrows.

Entity Relationship Diagram (ERD)

ERDs show the relationships between entities in a database, useful for designing and understanding data structures.

erDiagram
    CUSTOMER }|..|{ DELIVERY-ADDRESS : has
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER ||--o{ INVOICE : "liable for"
    DELIVERY-ADDRESS ||--o{ ORDER : receives
    INVOICE ||--|{ ORDER : covers
    ORDER ||--|{ ORDER-ITEM : includes
    PRODUCT-CATEGORY ||--|{ PRODUCT : contains
    PRODUCT ||--o{ ORDER-ITEM : "ordered in"

• erDiagram specifies the diagram type.
• Relationships are denoted with different symbols (}|..|{, ||--o{, etc.).

Pie Chart

Pie charts represent data distribution in a circular format, showing the proportion of each category.

pie title Pets adopted by volunteers
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15

• pie specifies the diagram type.
• title sets the chart’s title.
• Categories and values are listed with their proportions.

Journey

Journey diagrams represent the steps involved in a process or scenario, showing different stages and actions.

journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 3: Me

• journey specifies the diagram type.
• section groups stages of the journey.
• Actions are listed with their durations and participants.

Requirement Diagram

Requirement diagrams represent system requirements and their relationships, useful for capturing and validating system needs.

requirementDiagram

requirement test_req {
    id: 1
    text: the test text.
    risk: high
    verifymethod: test
}

element test_entity {
    type: simulation
}

test_entity - satisfies -> test_req

• requirementDiagram indicates the diagram type.
• requirement and element define requirements and their properties.
• Relationships are shown with arrows.

GitGraph

GitGraph diagrams visualize Git repositories and branches, helping to understand the branching and merging history.

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
    commit

• gitGraph specifies the diagram type.
• commit represents a commit in the graph.
• branch, checkout, and merge commands show branch operations.

Introduction

This guide provides a comprehensive overview of how Rouge handles syntax highlighting for various programming languages and configurations, including code blocks, line numbering, and using Liquid tags for highlighting within Jekyll.

Codes

Sample output: This is sample output from a computer program.

Keyboard input: Ctrl + Shift + Esc

Inline code: {"firstName": "John","lastName": "Smith","age": 25}

Code Blocks

Unknown

{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}

Plaintext

A code block without syntax highlighting or using plaintext (the default) will look like this:

1
2
3
4
5
6
{
  "thisSyntax": error
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}

This block is displayed without any syntax-specific colors or formatting.

Line Numbers

By default, line numbers are not shown. To include line numbers, add the attribute class {: .d-lineno } before or after the code block:

Sample:

1
2
3
4
5
6
7
8
9
```json
{
  "thisSyntax": error
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}
```
{:.d-lineno} <!-- like this -->

Output:

1
2
3
4
5
6
{
  "thisSyntax": error
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}

This will enable line numbering in the highlighted code block.

Mark Lines

By default mark lines the class .hll

Sample:

1
2
3
4
5
6
7
8
9
```json
{
  "thisSyntax": error
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}
```
{:data-mark-lines='2 4'} <!-- like this -->

Output:

1
2
3
4
5
6
{
  "thisSyntax": error
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}

Liquid Tags

In addition to using markdown for code blocks, you can use Liquid’s {% highlight %} tag for syntax highlighting within Jekyll. This is how you use it:

This is a code block with syntax highlighting using the Liquid {% highlight %} tag:

Sample:

1
2
3
4
5
6
7
{% highlight ruby linenos mark_lines="1 2" %}
def print_hi(name)
  puts "Hi, #{name}"
end
print_hi('Tom')
#=> prints 'Hi, Tom' to STDOUT.
{% endhighlight %}

Output:

1
2
3
4
5
def print_hi(name)
  puts "Hi, #{name}"
end
print_hi('Tom')
#=> prints 'Hi, Tom' to STDOUT.

This example highlights Ruby code and marks specific lines (lines 1 and 2) to draw attention.

Advanced

Sample:

1
2
3
4
5
6
7
8
9
10
```cpp
#include <iostream>
using namespace std;

int main() {
  cout << "Hello World!";
  return 0;
}
```
{: data-code='name:"main.c";icon:"brand-cpp";href:"https://gist.github.com/sionta/a3e9dec5ae0453cf21543bf5332e7fe0";' }

Output:

1
2
3
4
5
6
7
#include <iostream>
using namespace std;

int main() {
  cout << "Hello World!";
  return 0;
}

Language Examples

Here are examples of how different languages are highlighted using Rouge:

Diff

The diff language shows changes between versions, with additions and deletions marked.

1
2
3
4
function addTwoNumbers (num1, num2) {
-  return 1 + 2
+  return num1 + num2
}

YAML

YAML syntax is used for configuration files and data serialization.

1
2
3
4
5
6
7
kramdown:
    input: GFM

# Generate social links.
social_links:
    - { title: GitHub, url: "https://github.com/sionta" }
    - { title: Twitter, url: "https://twitter.com/r007mmxv" }

TOML

TOML is a configuration file format designed for simplicity.

1
2
3
4
5
6
7
8
9
[social_links]
  name = "Andre Attamimi"
  github = "https://github.com/sionta"

[menu]
[[menu.header]]
identifier = "about"
name = "About"
url = "/about/"

HTML

HTML syntax is used for structuring web pages.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Document</title>
    </head>
    <body>
        <div id="app"></div>

        <!-- This is a single-line comment -->

        <script>
            document.getElementById("app").innerHTML = "<h1>Hello, World!</h1>";
        </script>
    </body>
</html>

SCSS

SCSS (Sassy CSS) extends CSS with variables and nested rules.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
@use "sass:math";

// This is a single-line comment

$font-size: 16px;
/* $line-height: 1.7rem; */
$line-height: 1.5;
$text-color: #121212;
$background-color: #f1f1f1;

body {
    font: 400 #{$font-size}/#{$line-height} "Lato", "Arial", sans-serif;
    color: $text-color;
    background-color: $background-color;
}

figcaption { @extend %small-font-size; }

%small-font-size {
  font-size: math.clamp(-1in, 1cm, 10mm); // 10mm
}

JavaScript

JavaScript is a scripting language used for creating interactive web applications.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// This is a single-line comment

class Person {
    constructor(name) {
        this.name = name;
    }

    greet() {
        console.log(`Hello, ${this.name}!`);
    }
}

const person = new Person("John");
person.greet();

Bash

Bash scripts are used for automating tasks in Unix-based systems.

1
2
3
4
5
6
7
8
#!/usr/bin/env bash

person($1) {
    echo "Hello, $1"
}

# This is a single-line comment
person("John")

PowerShell

PowerShell scripts are the powerfull of shell.

1
2
3
4
5
6
7
8
9
10
function Write-Person {
    param (
        [string]$Name
    )

    Write-Host "Hello, $Name"
}

# This is a single-line comment
Write-Person("John")

PHP

PHP is a server-side scripting language used for web development.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<?php
// This is a single-line comment

class Person {
    private $name;

    public function __construct($name) {
        $this->name = $name;
    }

    public function greet() {
        echo "Hello, {$this->name}!";
    }
}

$person = new Person('John');
$person->greet();
?>

Ruby

Ruby is an object-oriented programming language known for its simplicity.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
=begin
This is a multi-line comment
that spans multiple lines
=end

class Person
  attr_reader :name # This is a single-line comment

  def initialize(name)
    @name = name
  end

  def greet
    puts "Hello, #{@name}!"
  end
end

person = Person.new('John')
person.greet

Python

Python is a versatile, high-level programming language used in many domains.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
"""
This is a multi-line comment
that spans multiple lines
"""

class Person:
    def __init__(self, name):
        self.name = name # This is a single-line comment

    def greet(self):
        print(f"Hello, {self.name}!")

person = Person('John')
person.greet()

For further language list support here

Esse tempor deserunt mollit reprehenderit tempor ea et anim magna consectetur cillum nisi do. Et exercitation cupidatat duis labore eiusmod. Consequat consequat esse esse officia velit.

Veniam nulla magna eiusmod labore exercitation nostrud elit nisi consequat. Fugiat amet quis aliqua sint anim non ut ullamco nisi. Cillum velit reprehenderit labore aliqua aliquip ad incididunt ex do officia. Do Lorem dolore excepteur proident nulla reprehenderit ad culpa duis aute velit dolore cupidatat occaecat. Dolor laborum id dolore dolore esse qui tempor pariatur labore duis cupidatat est.

Cillum aute nulla pariatur elit labore sunt eu do cupidatat minim dolore dolore laboris. Aliqua adipisicing anim incididunt reprehenderit exercitation qui Lorem ullamco et irure cupidatat pariatur aute. Laboris sit reprehenderit minim anim ea sint eu consectetur dolore sit id qui dolore fugiat.

Anim irure nisi minim officia reprehenderit consectetur. Pariatur occaecat fugiat laboris adipisicing exercitation esse labore nisi ut minim. Laborum mollit in enim culpa quis. Reprehenderit sint pariatur sint sit quis exercitation adipisicing. Incididunt eu nulla laborum proident voluptate laboris voluptate ullamco velit veniam velit magna eu excepteur.

Ea irure pariatur aliquip mollit nostrud esse duis aliquip. Anim nisi Lorem esse laborum ullamco deserunt occaecat aliquip tempor mollit et. Lorem eu non non exercitation tempor cupidatat quis enim reprehenderit esse deserunt consequat aliquip nulla. Ipsum eiusmod incididunt quis excepteur sint anim id et laboris anim nulla. Nisi non quis et culpa ullamco.

Proident ullamco aliquip ut qui occaecat in do cillum excepteur. Excepteur ea id eiusmod culpa irure aliqua nulla in ad nulla sit. Non voluptate cillum velit tempor nostrud. Duis dolore ea dolor ipsum sunt aliqua pariatur officia duis id sunt. Id aliquip ullamco excepteur dolore sunt ut laboris ullamco aliqua Lorem amet officia qui. Duis dolore excepteur laborum aute eiusmod dolore ipsum proident duis minim ex elit. Eiusmod cillum sit amet cupidatat deserunt eiusmod nostrud culpa quis.

Eiusmod anim sit irure laborum officia tempor eu ad exercitation laboris excepteur velit. Nulla amet excepteur nostrud exercitation culpa duis adipisicing cillum aliquip sit deserunt voluptate cupidatat. Amet elit esse occaecat esse duis in tempor non commodo. Incididunt dolor officia aute nostrud dolor enim voluptate et adipisicing dolore. Duis irure fugiat laboris amet do proident aliqua et. Adipisicing non minim amet minim.

Eiusmod duis excepteur ea est fugiat elit laborum ex est. Mollit ea deserunt laboris occaecat eu. Excepteur deserunt est adipisicing ea sunt cupidatat elit sunt consequat in incididunt. Sit magna elit eu reprehenderit enim fugiat. Commodo ea aliqua proident laboris. Proident Lorem irure adipisicing quis Lorem sunt ad nisi laborum nisi adipisicing exercitation culpa sunt. Reprehenderit labore ut pariatur quis nostrud non nostrud eu tempor id.

Enim laborum elit mollit do tempor aliqua irure excepteur laborum. Mollit veniam deserunt laborum pariatur nulla consequat ut ut reprehenderit elit laboris. Ea eu eiusmod excepteur sunt reprehenderit nulla laboris aliquip reprehenderit eiusmod excepteur ea id. Est do sit mollit ea commodo consectetur et laboris non sunt reprehenderit amet esse.