Lecture 04 - Other Markdown extensions

There are many other extensions in particular in the Material Documentation, here are some that are activated in Mkdocs-et.

Content tabs

Content tabs are widely used in this document.

CC++

#include <stdio.h>

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

#include <iostream>

int main(void) {
  std::cout << "Hello world!" << std::endl;
  return 0;
}

This example was obtained by

=== "C"

    ``` c
    #include <stdio.h>

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

=== "C++"

    ``` c++
    #include <iostream>

    int main(void) {
      std::cout << "Hello world!" << std::endl;
      return 0;
    }
    ```

Admonition

Admonitions, also known as call-outs, are an excellent choice for including side content without significantly interrupting the document flow. Material for MkDocs provides several different types of admonitions and allows for the inclusion and nesting of arbitrary content.

For instance,

Printing numbers

This example shows how to print numbers in Python3:

for i in range(10):
    print(i)

is obtained by

!!! example "Printing numbers"

    This example shows how to print numbers in Python3:

    ``` py
    for i in range(10):
        print(i)
    ```

The title can be removed using an empty string "":

This call-out is without a title and was obtained with

!!! note ""

    This call-out is without a title ...

Different types of admonition are possible, see here.

Different types

They provide different icons and colors.

Collapsible blocs

Collapsible blocks are a special kind of admonition :

Block closed by default

The text is inside a collapsible block.

Block open by default:

The text is inside a collapsible block.

These examples are obtained by putting ??? or ???+ at the beginning:

??? note "Block closed by default"

    The text is inside a collapsible block.

???+ note "Block open by default:"

    The text is inside a collapsible block.

Floating paragraph

Sidebar

This text is in a floating paragraph, which will appear to the right of the normal text, or full width on mobile screens.

Floating paragraphs are also admonitions; they are inserted in the Markdown document before the normal text.

To obtain such a floating box, add before the title inline end to place the box to the right, or inline for left.

If there's insufficient space to render the admonition next to the block, the admonition will stretch to the full width of the viewport, e.g. on mobile viewports.

!!! info inline end "Sidebar"

    This text is in a floating paragraph, which will appear to the right of the
    normal text, or full width on mobile screens.

Image alignment

It is also possible to align the text next to an image.

If there's insufficient space to render the text next to the image, the image will stretch to the full width of the viewport, e.g. on mobile viewports.

This example was obtained with

![A Tux](../images/tux2.gif){ align=left }

As the Material's documentation states, it is not possible to add a caption to an image in pure Markdown. For that, you need to revert to HTML.

For instance,

can be obtained by

<figure>
  <img src="https://pageperso.lis-lab.fr/~edouard.thiel/ez-draw/images/bubblets.png"
       width="320" alt="Bubblets" />
  <figcaption>This is a caption</figcaption>
</figure>

Include a file

To include a file, write --8<-- "filename" on a line by itself. The natural place for these files is the directory skel-mkdocs-et/includes.

Here is the result of --8<-- "includes/example1.md" :

This is a simple example of a markdown file that will be included in some place with the --8<-- operator.

and there is the result of --8<-- "includes/example2.txt" :

This is a simple example of a text file. If included with the --8<-- operator, it will also be interpreted as markdown.