How-To

How-To#

Content Structure#

The following 📜 principles apply:

  • For each section of your content create a new sub-folder under source/content

  • Each sub-folder should contain an index.md file

  • …

Combining Content#

We want to display each slide as a separate site but combine several slides into a single static webpage.

To do so we can use the following pattern in eachindex.md file of a sub-folder in source/content:

{% if build == "slides" %}
<!-- BUILDING THE SLIDES -->
```{toctree}
:maxdepth: 2
:caption: MySubSection

./slide1
./slide2
```
{% else %}
<!-- BUILDING THE PAGES -->
```{include} ./slide1.md
```
```{include} ./slide2.md
```
{% endif %}

To do so we can follow this approach:

Creatre a 📚 page#

Folder structure

📂content
┣ 📄index.md
┗ 📂 mypage
   ┣ 📄index.md
   ┣ 📄slide1.md
   ┣ 📄slide2.md
   ┣ 📄slide3.md
   ┗ 📂figures
     ┗ 📊figure1.png

  1. Create a new sub-folder (e.g. 📂 mypage)

  2. Create for each slide a separate file (like 📄slide2.md)

  3. Add 📄index.md that imports and comines all slides

  4. Import 📄mypage/index.md in the toctree in 📄index.md

Creating a page 📄index.md#

  • Add the pages title (e.g. # myPage)

  • Use the {% if slide %}...{% else %}...{% endif %} to separate single slides and the page content

  • Within the {% if slide %}...{% else %} create a toctree and import the slides:

    ```{toctree}
:maxdepth: 2
./slide1
...
```

  • Include the slides in the {% else %}...{% endif%}

    <!-- BUILDING THE PAGES -->
```{include} ./slide1.md
```

  • Optionally add further content to the page in {% else %}...{% endif%}

    <!-- BUILDING THE PAGES -->
This is some additional text to introduce content from slide1
```{include} ./slide1.md
```
```{margin}
and some site note we want to add in the page
```

And here is how a full 📂mypage/📄index.md could look like:

📂mypage/📄index.md
# myPage

{% if slide %}
<!-- BUILDING THE SLIDES -->
```{toctree}
:maxdepth: 2
./slide1
...
```
{% else %}
<!-- BUILDING THE PAGES -->
```{include} ./slide1.md
```
...
{% endif %}

Finally, we still need to include the page:

Add the pages 📂mypage/📄index.md in 📂content/📄index.md:

📂content/📄index.md
```{toctree}
:maxdepth: 2
:caption: MyCourse

mypage/index
```

Conditional Content#

Within each included or imported .md file you can also specify what content you want to show in the slides and what should be shown in the page view. You can use:

  • `` or ... to include content only in the static page

  • or to include content only in the slide

The above slide1.md could look as follows:

{% if build == "slides" %}
# Slide 1 title
{% else %}
## Subtitle for slide 1 content
{% endif %}

**This text is both on the slide and in the pages
{% if slide %}
🤪 This in only on the slide 🤪
{% endif %}

{% if page %}
This text is only in the pages view and not on the slide
{% endif %}
Content