Contribute slide decks

This guide tries to describe the current way to prepare and contribute slide decks via the knowledge base.

🚧 The mechanism to prepare and render slide decks in the knowledge base is currently under construction. So this guide is incomplete.

Creation of slide decks is based on marp

1. Create a new markdown file test-slides.md
2. Add marp: true to the YAML frontmatter of the file.
3. Add content to the file just as you would do for a markdown text document.
4. Add --- (horizontal lines) as slide breaks

🚧 Repo file structure and where to store the slide deck is under construction

• preview via VS Code preview (cmd + k, v)
• export via VS Code command Marp: Export Slide Deck (to html or PDF) or right-click the Marp symbol in the top-right corner while in edit mode of the markdown file

Can be added as markdown comments.

These will appear in presenter mode (html) or in PDF (if "markdown.marp.pdf.noteAnnotations": true is added to the .vscode/settings.json)

• export to html (opens in browser) and hit the presentation icon

1280 x 720

• easy to adapt (from existing md content)
• customizable (requires css and / or html skills)
• can directly render draw.io images

• theme needs to be linked (also) via .vscode/settings.json

https://www.hashbangcode.com/article/seven-tips-getting-most-out-marp

Custom themes based on CSS are currently stored in src/docs/teaching-materials/style/

In order to work with the VS Code marp extension (i.e. preview and export slides to pdf, html, etc.), you might want to add the following to the gitignored VS code settings (.vscode/settings.json) of this repo. If the file does not exist, please create it.

• If images are not properly linked, marp cannot parse and render them in pdf or html.
• the VS Code extension will not throw a warning and just ouput an empty (figure-less) slide
• There's an easy way to find the missing / incorrect image links on the html version of your marp slides using your browser described here:

https://github.com/marp-team/marp/discussions/257

Please check out the rendered example slide deck. And compare it to its source markdown.

DataPLANT Support