Documentation

Tinh Vo

Technische Universität Darmstadt

02 Jul, 2025

Meta

Codeblock template: TBD

Codeblock template: TBD with callout in

  :::  {.callout-tip icon=false title="TBD" } 
  :::

BUGs

  • List right after ::: block will not work: Need a line of content before
  • (see more bugs in Lists)
  • best practice is to have empty line after header - lots of bugs otherwise
  • columns after list item is mega bugged???

(extended syntax for qmd is at the end)

Content alignment

To manual line break, \n will not work -> use <br>

Centering

Centering : There is only one option known to work, style="text-align:center". Put this into delimiters

In fact, anything to be centered can enter a centered generic block, including images

Codeblock template: centered block (of anything)

::: {.block style="text-align:center"}
:::

Overlaying

You can stack stuff on top of each other (any block) with the .r-stack property

See how it works? {.fragment}

.r-stack behaviour:

  • .fragment implicitly splits into blocks not marked with .fragment to group with ones above.

Columns

  • To use with .columns, care is needed:
    • force full width for columns style="width: 100%;"
    • properly .block other contents ::: {.block}
    • only split col inside ::: {.column} :::
    • Collumn size with width=
      • WARNING! style="width: 40%" is NOT correct!

2 Columns

Codeblock template: 2 Columns

:::: {.columns style="width: 100%;" .fragment}

::: {.column width="50%"}
Content left
::: 
<!-- left col -->

::: {.column width="50%" style="text-align:left" .fragment}
Content right
::: 
<!-- right col -->

:::: 
<!-- cols -->

Results in

Content left

Content right

2 Columns + center overlay

Codeblock template: 3 Columns

:::::: {.r-stack }


:::: {.columns style="width: 100%;" .fragment}

::: {.column width="50%"}
Content left
::: 
<!-- left col -->

::: {.column width="50%" style="text-align:right"}
Content right
::: 
<!-- right col -->

:::: 
<!-- cols -->

::: {.block .fragment}
Content after
::: 
<!-- middle overlay -->

:::::: 
<!-- 3-cols block -->

Results in

Content left

Content right

Content after

2x2 Grid

Codeblock template: 3 Columns

:::: {.columns style="width: 100%;"}

::: {.column width="50%" .fragment fragment-index=1}

TopLeft

::: 
<!-- left col -->


::: {.column  width="50%" style="text-align:left" .fragment}

TopRight

::: 
<!-- right col -->

:::: 
<!-- top cols -->


:::: {.columns style="width: 100%;" .fragment}

::: {.column width="50%"}
BottomLeft
::: 
<!-- left col -->

::: {.column width="50%" style="text-align:left" .fragment}
BottomRight
::: 
<!-- right col -->

:::: 
<!-- bottom cols -->

TopLeft

TopRight

BottomLeft

BottomRight

Column-Photo integration

  • To keep generality , instead of a permutation of photo inclusion for each column:
    • assume that there is any column
    • wrap overlay of photo around it
::: {.column  ...}

content

::: 
<!-- col -->

add :::::: {.r-stack } above

  • add after to make TBD aligned photo block:

    ::: {.block style="text-align:right"}
![Caption](/@Medias/me.jpg){width="2in" style="text-align:center"}
::: 
<!-- img overlay -->

:::::: 
<!-- col++ -->

  • add after to make column split:

    ::: {.column width="50%" style="text-align:right"}
![Caption](/@Medias/me.jpg){width="2in" style="text-align:center"}
::: 
<!-- img overlay -->

:::::: 
<!-- col++ -->


test for block:

content

Caption

test for column split:

content

Caption

Photo management

Codeblock template: Image

![Caption](/@Medias/me.jpg){width="2in" style="text-align:center"}

results in

Caption
    • Positioning : a verbose example
      {.absolute top=200 left=0 width="350" height="300"}, vice versa
    • Best pratice: put into columns
  • Overlaying

    • Codeblock template: Overlaid image, 1 step

      ::: {.r-stack}
Overlaid text
:::: {.fragment}
![Caption](/@Medias/me.jpg){width="2in" style="text-align:center"}
:::: 
<!-- overlay img -->
::: 
<!-- text-img overlay block -->

      results in

      Overlaid text

      Caption

    • Codeblock template: Overlaid image, 2 steps

      ::: {.r-stack}
:::: {.fragment}
{Overlaid text}
:::: 
<!-- text underneath -->
:::: {.fragment}
![Caption](/@Medias/me.jpg){width="2in" style="text-align:center"}
:::: 
<!-- overlay img -->
::: 
<!-- text-img overlay block -->

      results in

      {Overlaid text}

      Caption

Alignment

  • Centering : fig-align="center"

Formatting

  • Apply like {style="key:value;"}
    • or .smaller
  • Applicable {key}s:
    • font-size: {#}%;
  • .scrollable scroll long code
  • .fragment delay display until next arrow cmd
  • style="text-align:center" to align center anything (text)
  • .r-stretch vertical stretch to fill (no wrapping)
    • Disable: {.nostretch}
  • Tabs : ::: {.panel-tabset} ::: , with ### being each tab
    • this is also quite dangerous with header level

Flow control

WARNING!

using line break --- to force new slide will confuse yaml header -> unsafe

Instead , use other line break strings like *** or ___

Fragments

For a text:

Normal fragment are its own line/block , wrapped in .fragment

But if you want to do it inline,

use :::: {.inline-fragment} (4x:) in addition, wrapping the block.

this was hacked with css

For irregular order, add fragment-index=

indexed fragments will show first by defaul ie. cannot intercept ordering implicitly

For an equation: \[ x = \class{fragment}{{} x(x+1) + 1(x+1)} \] Use \class{fragment}{ ... } , but ordering appearance here is impossible

Increment(al)

automatic .fragment

  • List items are auto
  • incremented

Citations

Citation with footnotes 1 via:

  • Codeblock template: Citation / Footnote

      ::: aside
  [1] TBD
  :::

  • Codeblock template: inline Citation

      ^[TBD 2.]

Python embed

Render code with “{.code}” eg. {.python}

  • Highlight lines code-line-numbers=, no spaces!
  • Incremental highlights with | separation
  • Leave the entire block highlighted with | at start
  • eg. {.python code-line-numbers="7,9|10"}
#| label: fig-1
#| fig-cap: "Demo plot name"
#| echo: true
#| output-location: column

import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(  subplot_kw = {'projection': 'polar'} )
ax.plot(theta, r);ax.set_rticks([0.5, 1, 1.5, 2]); ax.grid(True) ; plt.show()

tagalong css styles with style="key:value;"
code wrapping does not work (yet)

Figure 1: Demo plot name

(see forced squashing) Code should be separate from source items, size adjustment & other formatting likely

Or to dump the plot to next slide (no heading), use

#| echo: true
#| output-location: column

Python embed 2

To really echo true source, use output options:

  • fragment
  • slide
  • column
  • column-fragment (just a combi)
import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(  subplot_kw = {'projection': 'polar'} 
,figsize=(3,3)) # this for size 
ax.plot(theta, r);
ax.set_rticks([0.5, 1, 1.5, 2]); 
ax.grid(True) ; plt.show()
Figure 2: Source-echoed plot

Python embed - external possibilities

Demonstrating persistent header

Is a global switch. Individual persistence currently impossible

Incremental slides , also let’s say that this section is really long so that the next h3 will include it all for sizing

(this is to test reveal-header)

Subsubsection

This is a check for persistent header: h2 is included h3 will not be included in header persistence -> needs to be numbered and retyped

This h2 change should have dismissed the last one

h3

content..

h3,2

content…

h4

here we see a need for h3 persistence: h3 has to be manually retyped again!

qmd basics (are different)

Lists

Newline requirements are strict. Before anyblock needs a newline to break that block - anything is a block

  • List:

  • Codeblock template:New List

    
- TBD
  • List with callout :

  • Codeblock template:New List with callout

    
-  ::: {.callout-tip icon=false title="TBD"}
   TBD
   ::: 
   <!-- callout -->

Callouts

Restrictions with list

  • Must take a whole list item ie. no before or after
  • ::: indent must EXACT

Built-in

  • {.callout-note}
  • {.callout-tip}
  • {.callout-caution}
  • {.callout-warning}
  • {.callout-important}

  • Standard callout

        ::: {.callout-tip icon=false title="TBD" } 

    ::: <!-- callout -->

  • Codeblock template:new list item with Callout

    - ::: {.callout-tip icon=false title="TBD"}
  TBD
  ::: <!-- callout -->

  • Callout with code block inside

    Caution

    ` Must be on the exact indent as :::

    ::: {.callout-tip icon=false title="Standard callout" } 

    ```

    ```

::: <!-- callout -->

Controls

  • Zoom: Alt + Click (or Ctrl + Click on Linux)
  • Speaker view: press s
  • Click the hamburger menu or press m
  • Black out: press b
  • Code anim: with ## {auto-animate=true} between 2 codeblocks

Separating slides

Codeblock template: include chapters

<!-- {{< include /path/to/_file.qmd >}} -->