Markdown

This Markdown cheat sheet provides a quick overview of all the Markdown syntax elements. It can’t cover every edge case, so if you need more information about any of these elements, refer to the reference guides for basic syntax and extended syntax.

Basic Syntax

These are the elements outlined in John Gruber’s original design document. All Markdown applications support these elements.

Heading

# H1
`# H1`
## H2
`## H2`
### H3
`### H3`

bold text **bold text**

The world is flat. ~~The world is flat.~~

italicized text *italicized text*

New line

<p>&nbsp;</p> or <br> and <br/>

Custom Blockquote

> blockquote or <blockquote></blockquote>

blockquote

These custom styles can be used by adding the specific class to the blockquote, as follows:

> ##### TIP
>
> A tip can be used when you want to give advice
> related to a certain content.
{: .block-tip }

TIP

A tip can be used when you want to give advice related to a certain content.

> ##### WARNING
>
> This is a warning, and thus should
> be used when you want to warn the user
{: .block-warning }

WARNING

This is a warning, and thus should be used when you want to warn the user

> ##### DANGER
>
> This is a danger zone, and thus should
> be used carefully
{: .block-danger }

DANGER

This is a danger zone, and thus should be used carefully

Ordered List

1. First item 1. First item
2. Second item 2. Second item
3. Third item 3. Third item

Unordered List

• First item - First item
• Second item - Second item
• Third item - Third item

Code

code code

Horizontal Rule

--- or <hr>

Link

Markdown Guide [Markdown Guide](https://www.markdownguide.org)

Image

![alt text](https://www.markdownguide.org/assets/images/tux.png)

Table

| Syntax | Description |
| ----------- | ----------- |
| Header | Title |
| Paragraph | Text |

Fenced Code Block

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

Footnote

Here’s a sentence with a footnote. ¹ [^1]

[^1]: This is the footnote.

Task List

• Write the press release
• Update the website
• Contact the media - [x] Write the press release - [ ] Update the website - [ ] Contact the media

Emoji

That is so funny! :joy:

(See also Copying and Pasting Emoji)

Table of contents

To add a table of contents to a post, simply add

toc:
  beginning: true

to the front matter of the post. The table of contents will be automatically generated from the headings in the post. If you want to learn more about how to customize the table of contents, you can check the jekyll-toc repository.

Table of contents sidebar

To add a table of contents to a post as a sidebar, simply add

toc:
  sidebar: left

to the front matter of the post. The table of contents will be automatically generated from the headings in the post. If you wish to display the sidebar to the right, simply change left to right.

If you want to learn more about how to customize the table of contents of your sidebar, you can check the bootstrap-toc documentation. Notice that you can even customize the text of the heading that will be displayed on the sidebar.

Images

---
layout: post
title:  a post with images
date: 2015-05-15 21:01:00
description: this is what included images could look like
tags: formatting images
categories: sample-posts
thumbnail: assets/img/9.jpg
---

This is an example post with image galleries.

Images can be made zoomable. Simply add data-zoomable to <img> tags that you want to make zoomable.

The rest of the images in this post are all zoomable, arranged into different mini-galleries.

Audios

This is an example post with audios. It supports local audio files.

Videos

This is an example post with videos. It supports local video files.

It does also support embedding videos from different sources. Here are some examples:

A post with redirecting

---
layout: post
title: a post with redirect
date: 2022-02-01 17:39:00
description: you can also redirect to assets like pdf
redirect: /assets/pdf/example_pdf.pdf

---

Redirecting to another page.

Twitter

Tweet An example of displaying a tweet:

Timeline An example of pulling from a timeline:

Additional Details For more details on using the plugin visit: jekyll-twitter-plugin

Diagrams

This theme supports generating various diagrams from a text description using jekyll-diagrams plugin. Below, we generate a few examples of such diagrams using languages such as mermaid, plantuml, vega-lite, etc.

Note: different diagram-generation packages require external dependencies to be installed on your machine. Also, be mindful of that because of diagram generation the fist time you build your Jekyll website after adding new diagrams will be SLOW. For any other details, please refer to jekyll-diagrams README.

Mermaid Install mermaid using node.js package manager npm by running the following command:

npm install -g mermaid.cli

The diagram below was generated by the following code:

{% mermaid %}
sequenceDiagram
    participant John
    participant Alice
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
{% endmermaid %}

Math

This theme supports rendering beautiful math in inline and display modes using MathJax 3 engine. You just need to surround your math expression with $$, like $$ E = mc^2 $$. If you leave it inside a paragraph, it will produce an inline expression, just like \(E = mc^2\).

To use display mode, again surround your expression with $$ and place it as a separate paragraph. Here is an example:

You can also use \begin{equation}...\end{equation} instead of $$ for display mode math. MathJax will automatically number equations:

\begin{equation} \label{eq:cauchy-schwarz} \left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right) \end{equation}

and by adding \label{...} inside the equation environment, we can now refer to the equation using \eqref.

Note that MathJax 3 is a major re-write of MathJax that brought a significant improvement to the loading and rendering speed, which is now on par with KaTeX.

Code

This example is in C++. All you have to do is wrap your code in markdown code tags:

```c++
code code code
```

int main(int argc, char const \*argv[])
{
    string myString;

    cout << "input a string: ";
    getline(cin, myString);
    int length = myString.length();

    char charArray = new char * [length];

    charArray = myString;
    for(int i = 0; i < length; ++i){
        cout << charArray[i] << " ";
    }

    return 0;
}

For displaying code in a list item, you have to be aware of the indentation, as stated in this Stackoverflow answer. You must indent your code by (3 * bullet_indent_level) spaces. This is because kramdown (the markdown engine used by Jekyll) indentation for the code block in lists is determined by the column number of the first non-space character after the list item marker. For example:

1. We can put fenced code blocks inside nested bullets, too.
   1. Like this:
      ```c
      printf("Hello, World!");
      ```

   2. The key is to indent your fenced block in the same line as the first character of the line.

Which displays:

1. We can put fenced code blocks inside nested bullets, too.
   1. Like this:

      printf("Hello, World!");
      

   2. The key is to indent your fenced block in the same line as the first character of the line.

By default, it does not display line numbers. If you want to display line numbers for every code block, you can set kramdown.syntax_highlighter_opts.block.line_numbers to true in your _config.yml file.

If you want to display line numbers for a specific code block, all you have to do is wrap your code in a liquid tag:

{% highlight c++ linenos %}
code code code
{% endhighlight %}

The keyword linenos triggers display of line numbers. Produces something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
int main(int argc, char const \*argv[])
{
    string myString;

    cout << "input a string: ";
    getline(cin, myString);
    int length = myString.length();

    char charArray = new char * [length];

    charArray = myString;
    for(int i = 0; i < length; ++i){
        cout << charArray[i] << " ";
    }

    return 0;
}
 

Citations and quoting

---
layout: distill
title: a distill-style blog post
description: an example of a distill-style blog post and main elements
tags: distill formatting
giscus_comments: true
date: 2021-05-22
featured: true
---

authors:

• name: Albert Einstein url: “https://en.wikipedia.org/wiki/Albert_Einstein” affiliations: name: IAS, Princeton
• name: Boris Podolsky url: “https://en.wikipedia.org/wiki/Boris_Podolsky” affiliations: name: IAS, Princeton
• name: Nathan Rosen url: “https://en.wikipedia.org/wiki/Nathan_Rosen” affiliations: name: IAS, Princeton

bibliography: 2018-12-22-distill.bib

Optionally, you can add a table of contents to your post. NOTES:

• make sure that TOC names match the actual section names for hyperlinks within the post to work correctly.
• we may want to automate TOC generation in the future using jekyll-toc plugin (https://github.com/toshimaru/jekyll-toc). toc:
• name: Equations if a section has subsections, you can add them as follows: subsections:
  • name: Example Child Subsection 1
  • name: Example Child Subsection 2
• name: Citations
• name: Footnotes
• name: Code Blocks
• name: Interactive Plots
• name: Layouts
• name: Other Typography?

Below is an example of injecting additional post-specific styles. If you use this post as a template, delete this _styles block. _styles: > .fake-img { background: #bbb; border: 1px solid rgba(0, 0, 0, 0.1); box-shadow: 0 0px 4px rgba(0, 0, 0, 0.1); margin-bottom: 12px; } .fake-img p { font-family: monospace; color: white; text-align: left; margin: 12px 0; text-align: center; font-size: 16px; }

Equations

This theme supports rendering beautiful math in inline and display modes using MathJax 3 engine. You just need to surround your math expression with $$, like $$ E = mc^2 $$. If you leave it inside a paragraph, it will produce an inline expression, just like \(E = mc^2\).

To use display mode, again surround your expression with $$ and place it as a separate paragraph. Here is an example:

Note that MathJax 3 is a major re-write of MathJax that brought a significant improvement to the loading and rendering speed, which is now on par with KaTeX.

Citations

Citations are then used in the article body with the <d-cite> tag. The key attribute is a reference to the id provided in the bibliography. The key attribute can take multiple ids, separated by commas.

The citation is presented inline like this: (a number that displays more information on hover). If you have an appendix, a bibliography is automatically created and populated in it.

Distill chose a numerical inline citation style to improve readability of citation dense articles and because many of the benefits of longer citations are obviated by displaying more information on hover. However, we consider it good style to mention author last names if you discuss something at length and it fits into the flow well — the authors are human and it’s nice for them to have the community associate them with their work.

Footnotes

Just wrap the text you would like to show up in a footnote in a <d-footnote> tag. The number of the footnote will be automatically generated.This will become a hoverable footnote.

Code Blocks

Syntax highlighting is provided within <d-code> tags. An example of inline code snippets: <d-code language="html">let x = 10;</d-code>. For larger blocks of code, add a block attribute:

Note: <d-code> blocks do not look good in the dark mode. You can always use the default code-highlight using the highlight liquid tag:

var x = 25;
function(x) {
  return x * x;
}

Interactive Plots

You can add interative plots using plotly + iframes

The plot must be generated separately and saved into an HTML file. To generate the plot that you see above, you can use the following code snippet:

import pandas as pd
import plotly.express as px
df = pd.read_csv(
  'https://raw.githubusercontent.com/plotly/datasets/master/earthquakes-23k.csv'
)
fig = px.density_mapbox(
  df,
  lat='Latitude',
  lon='Longitude',
  z='Magnitude',
  radius=10,
  center=dict(lat=0, lon=180),
  zoom=0,
  mapbox_style="stamen-terrain",
)
fig.show()
fig.write_html('assets/plotly/demo.html')

Details boxes

Details boxes are collapsible boxes which hide additional information from the user. They can be added with the details liquid tag:

Layouts

The main text column is referred to as the body. It is the assumed layout of any direct descendants of the d-article element.

For images you want to display a little larger, try .l-page:

All of these have an outset variant if you want to poke out from the body text a little bit. For instance:

Occasionally you’ll want to use the full browser width. For this, use .l-screen. You can also inset the element a little from the edge of the browser by using the inset variant.

The final layout is for marginalia, asides, and footnotes. It does not interrupt the normal flow of .l-body sized text except on mobile screen sizes.

Other Typography?

Emphasis, aka italics, with asterisks (*asterisks*) or underscores (_underscores_).

Strong emphasis, aka bold, with asterisks or underscores.

Combined emphasis with asterisks and underscores.

Strikethrough uses two tildes. Scratch this.

1. First ordered list item
2. Another item ⋅⋅* Unordered sub-list.
3. Actual numbers don’t matter, just that it’s a number ⋅⋅1. Ordered sub-list
4. And another item.

⋅⋅⋅You can have properly indented paragraphs within list items. Notice the blank line above, and the leading spaces (at least one, but we’ll use three here to also align the raw Markdown).

⋅⋅⋅To have a line break without a paragraph, you will need to use two trailing spaces.⋅⋅ ⋅⋅⋅Note that this line is separate, but within the same paragraph.⋅⋅ ⋅⋅⋅(This is contrary to the typical GFM line break behaviour, where trailing spaces are not required.)

• Unordered list can use asterisks
• Or minuses
• Or pluses

I’m an inline-style link

I’m an inline-style link with title

I’m a reference-style link

I’m a relative reference to a repository file

You can use numbers for reference-style link definitions

Or leave it empty and use the link text itself.

URLs and URLs in angle brackets will automatically get turned into links. http://www.example.com or http://www.example.com and sometimes example.com (but not on Github, for example).

Some text to show that the reference links can follow later.

Here’s our logo (hover to see the title text):

Inline-style:

Reference-style:

Inline code has back-ticks around it.

var s = "JavaScript syntax highlighting";
alert(s);

s = "Python syntax highlighting"
print s

No language indicated, so no syntax highlighting.
But let's throw in a <b>tag</b>.

Colons can be used to align columns.

There must be at least 3 dashes separating each header cell. The outer pipes (|) are optional, and you don’t need to make the raw Markdown line up prettily. You can also use inline Markdown.

Blockquotes are very handy in email to emulate reply text. This line is part of the same quote.

Quote break.

This is a very long line that will still be quoted properly when it wraps. Oh boy let’s keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can put Markdown into a blockquote.

Here’s a line for us to start with.

This line is separated from the one above by two newlines, so it will be a separate paragraph.

This line is also a separate paragraph, but… This line is only separated by a single newline, so it’s a separate line in the same paragraph.

Github metadata

layout: post title: a post with github metadata date: 2020-09-28 21:01:00 description: a quick run down on accessing github metadata. tags: metadata categories: sample-posts external-services —

A sample blog page that demonstrates the accessing of github meta data.

What does Github-MetaData do?

• Propagates the site.github namespace with repository metadata
• Setting site variables :
  • site.title
  • site.description
  • site.url
  • site.baseurl
• Accessing the metadata - duh.
• Generating edittable links.

Additional Reading

• If you’re recieving incorrect/missing data, you may need to perform a Github API authentication.
• Go through this README for more details on the topic.
• This page highlights all the feilds you can access with github-metadata.
  

Example MetaData

• Host Name :
• URL :
• BaseURL :
• Archived :
• Contributors :