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.
#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,
![Bubblets](https://pageperso.lis-lab.fr/~edouard.thiel/ez-draw/images/bubblets.png)
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.