Lecture 02 - More Markdown

Here is the second part of the Markdown basic syntax.

Code

To denote a word or phrase as code, enclose it in backticks `...`. Moreover, syntactic colouring can be achieved by specifying the language name with `:::language ...`, thanks to the extension InlineHilite.

For instance,

In bash, the command `:::bash echo "$s" | tr "a-z" "A-Z"` prints the value of `s` in a pipe `|`, which is read by `tr`.

will produce :

In bash, the command echo "$s" | tr "a-z" "A-Z" prints the value of s in a pipe |, which is read by tr.

Code blocks are normally indented four spaces or one tab. But it's more practical to surround them with three backticks without indent :

MarkdownRendered Output

```
This is a block of code
which is spread over several lines
```

This is a block of code
which is spread over several lines

The tabs are preserved for copy and paste :

MarkdownRendered Output

```
cat <<- EOT
    there is a tab here !!
    EOT
```

cat <<- EOT
	there is a tab here !!
	EOT

For syntactic colouring, add the language name after the first ```:

MarkdownRendered Output

``` c
#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
  return 0;
}
```

#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
  return 0;
}

The lines can be numbered and highlighted as well:

MarkdownRendered Output

``` c linenums="3" hl_lines="1 4"
#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
  return 0;
}
```

#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
  return 0;
}

The list of available languages is here.

Horizontal rules

An horizontal rule is obtained with --- on a line by itself, surrounded by blank lines:

---

Links

A link can be obtained by enclosing an URL in <...>.

To create a named link, enclose the link text in brackets [...] and then follow it immediately with the URL in parentheses (...).

For instance,

My favourite web framework is [Django](https://www.djangoproject.com/).

will render as

My favourite web framework is Django.

Another solution, especially useful when the URL is long or used several times, is to split the URL with a label n in a [reference text][n] and a [n]: reference link. The latter can be inserted in any place in the document :

MarkdownRendered Output

My favourite web framework is [Django][1].

The [Django][1] framework provide a [template language][2].

[1]: https://www.djangoproject.com/
[2]: https://docs.djangoproject.com/en/3.1/ref/templates/language/

My favourite web framework is Django.

The Django framework provide a template language.

Links can also been emphasized with *...*, **...** or `...` like this :

MarkdownRendered Output

My favourite web framework is *[Django][1]*.

The **[Django][1]** framework provide a [`template language`][2].

[1]: https://www.djangoproject.com/
[2]: https://docs.djangoproject.com/en/3.1/ref/templates/language/

My favourite web framework is Django.

The Django framework provide a template language.

Images

To add an image, add an exclamation mark !, followed by alt text in brackets, and the path or URL to the image asset in parentheses. You can optionally add a title after the URL in the parentheses: ![alt_text](URL "title")

MarkdownRendered Output

![a Tux](../images/tux2.gif "A Tux with a bucket hat")

The URL can also be split with a reference label:

MarkdownRendered Output

![Linux Penguin][3]

[3]: https://pageperso.lis-lab.fr/~edouard.thiel/images/penguineyes.gif "Dancing penguin"

Escaping Characters

To display a literal character that would otherwise be used to format text in a Markdown document, add a backslash \ in front of the character.

Thanks to the pymdownx.escapeall extension, you can use a backslash to escape all characters (outside of a block code).

MarkdownRendered Output

\\ \` \* \_ \{ \} \[ \] \< \> \( \) \# \+ \- \. \! \|  
\a \B \é \É \ç \@ \§ \~ \, \; \: \?

\ ` * _ { } [ ] < > \( \) # + - . ! |
a B é É ç @ § ~ , ; : ?

HTML

HTML tags can be inserted, they will be copied as is. HTML comments will be copied too.

MarkdownRendered Output

This world is **bold**, this world is <em>italic</em>.

<!-- This comment will be copied in the html ouput -->

This world is bold, this world is italic.

If you need to hide comments from the source, use Jinja2 comments:

{# This comment will not appear 
   in the HTML output #}
<!-- This comment will appear -->

By default, Markdown ignores any content within a raw HTML block-level (non indented) element. Thanks to the md_in_html extension, the content can be parsed as Markdown by including a markdown="1" on the opening tag. For example,

<div>
This is a *Markdown* Paragraph.
</div>

<div markdown="1">
This is a *Markdown* Paragraph.
</div>

will be rendered as

This is a *Markdown* Paragraph.

This is a Markdown Paragraph.

Finally, HTML entities are copied too; for instance, é <   > @ will produce é <   > @.