This repository defines the Knowledge Pods Approach (KPA), an agile way to create, maintain and evolve training materials and presentations using standard markdown files to create beautiful slide sets and agendas.
The Knowledge Pods Approach (KPA) is a method for creating training materials, presentations and documentation that separates the content creation (the knowledge) from their presentation (the files, i.e. pdf, ppt and html).
KPA relies on the standard markdown file format, which means that there will be no need to rely on proprietary tools and formats to create contents.
KPA helps to concentrate on what matters most: the knowledge.
KPA is at the same time:
A KPA project is a set of variables and markdown files that are used by the Ansible role named kpa_generator to automate the creation of a single combined markdown file that can be processed by Marp (Markdown Presentation Ecosystem) to obtain a set of slides in the usual presentation formats like html, pdf and ppt. The kpa_generator Ansible role generates also an agenda markdown that is converted to a PDF using the Pandoc tool.
KPA makes it possible to control all the knowledge in a standard and "edit from everywhere" way, making it easy to compose and mix the set of topics you want to include into the training, by creating sequences of Knowledge Pods (KP).
A Knowledge Pod (KP) is the smallest part you can split a section of a training or of a presentation.
You can imagine it as a chapter. For example, if you need to deliver a training named "How to use my technology" in which you'll have to cover an introduction to your technology, the prerequisites, the installation and finally day 0 operation, then each one of these chapters would be a Knowledge Pod, like:
A Knowledge Pod should have, uniformly, the same duration (say one hour), so that it will be easy to compose a training by picking the needed KPs.
Each section of a Knowledge Pod, say a paragraph, is separated from the
other with the ---
Markdown element, which represents a new slide.
There are several benefits using KPA:
After cloning this repository:
> git clone https://github.com/mmul-it/kpa.git
Cloning into 'kpa'...
remote: Enumerating objects: 125, done.
remote: Counting objects: 100% (125/125), done.
remote: Compressing objects: 100% (59/59), done.
remote: Total 125 (delta 51), reused 114 (delta 43), pack-reused 0
Receiving objects: 100% (125/125), 3.88 MiB | 3.38 MiB/s, done.
Resolving deltas: 100% (51/51), done.
> cd kpa
You'll see a projects
directory, which is meant to contain all your KPA
projects. You can use example
project as your starting point.
This is the structure of a KPA project:
projects/example/
├── common
│ ├── settings.yml
│ ├── example.tex
│ └── theme.css
├── images
│ ├── chapter-background.png
│ ├── cover-background.png
│ ├── logo.png
│ └── slide-background.png
├── templates
│ ├── chapter.md.j2
│ └── cover.md.j2
├── contents
│ ├── Topic-10.md
│ ├── ...
│ └── Topic-18.md
└── Example-Training-01.yml
Where:
common: is the home for shared training/presentation files:
theme.css is the css theme file that overrides Marp's default theme. This is not needed, you can use a predefined Marp theme.
example.tex is the Pandoc texfile template. This is not strictly needed, but to get the best from the generated agenda pdf a Pandoc template is more than reasonable.
settings.yml is mandatory and contains the general presentation parameters that will override role's defaults:
---
# KPA
kpa_project_dir: 'projects/example'
kpa_author: 'Raoul Scarazzini'
kpa_copyright: '© 2023 MiaMammaUsaLinux.org'
# Pandoc
pandoc_agenda_template_file: "{{ kpa_project_dir }}/common/example.tex"
pandoc_agenda_background_image: "{{ kpa_project_dir }}/images/schedule-background.png"
pandoc_agenda_header_includes:
- '\usepackage{booktabs}'
- '\usepackage{longtable}'
- '\usepackage{array}'
- '\usepackage{multirow}'
- '\usepackage{wrapfig}'
- '\usepackage{float}'
- '\usepackage{colortbl}'
- '\usepackage{pdflscape}'
- '\usepackage{tabu}'
- '\usepackage{threeparttable}'
- '\usepackage{threeparttablex}'
- '\usepackage[normalem]{ulem}'
- '\usepackage{makecell}'
# Marp
marp_theme: example
marp_theme_file: "{{ kpa_project_dir }}/common/theme.css"
marp_background_color: #ffffff
marp_background_image: "{{ kpa_project_dir }}/images/slide-background.png"
marp_paginate: true
marp_cover_template: "{{ kpa_project_dir }}/templates/cover.md.j2"
marp_cover_image: "{{ kpa_project_dir }}/images/cover-image.png"
marp_cover_logo: "{{ kpa_project_dir }}/images/logo.png"
marp_cover_background_image: "{{ kpa_project_dir }}/images/cover-background.png"
marp_chapter_template: "{{ kpa_project_dir }}/templates/chapter.md.j2"
marp_chapter_background_image: "{{ kpa_project_dir }}/images/chapter-background.png"
images contains backgrounds, logos and all the useful graphics elements for the slides.
templates contains the templates for the special slides that will be processed by Ansible. These templates will parse the variables, to be reusable. For example, the chapter.md.j2 contains the layout for the slide that will be shown at the beginning of each KP/Chapter:
---
<!-- _backgroundImage: url({{ marp_chapter_background_image }}) -->
# <span class="txt-yellow">{{ slide.title }}</span>
<span class="txt-yellow">{{ slide.chapter }}</span>
The variables used in this file can be declared globally (like
marp_chapter_backgroundImage
, see slides-settings.yml)
or specifically (like slide.title
, see Example-Training-01.yml).
contents contains the Knowledge Pods in the
Marp Markdown compatible format (The main
rule: ---
is the beginning of a new slide).
Example-Training-01.yml is the slides set declaration, it contains the structure of the document, in a list element:
---
# KPA
kpa_title: "My spectacular course"
kpa_contents: "{{ kpa_project_dir }}/contents"
kpa_slides:
# DAY 1
- cover: true
title: "{{ kpa_title }}"
subtitle: "DAY ONE"
- chapter: 'DAY ONE - PART ONE'
title: 'Topic 1'
content: "{{ kpa_contents }}/Topic-1.md"
- chapter: 'DAY ONE - PART TWO'
title: 'Topic 2'
content: "{{ kpa_contents }}/Topic-2.md"
...
...
# Day 2
- cover: true
title: "{{ kpa_title }}"
subtitle: "DAY TWO"
- chapter: 'DAY TWO - PART SEVEN'
title: 'Topic 7'
content: "{{ kpa_contents }}/Topic-7.md"
...
...
# Day 3
- cover: true
title: "{{ kpa_title }}"
subtitle: "DAY THREE"
- chapter: 'DAY THREE - PART THIRTEEN'
title: 'Topic 13'
content: "{{ kpa_contents }}/Topic-13.md"
...
...
- chapter: 'DAY THREE - PART EIGHTEEN'
title: 'Topic 18'
content: "{{ kpa_contents }}/Topic-18.md"
# Output
output_file: "slides/Example-Training-01"
schedule_output_file: "{{ output_file }}.schedule.md"
marp_output_file: "{{ output_file }}.md"
KPA comes with a handy container that can be used to automate the creation of both the slides and the agenda PDF files.
Once you have a local project in place:
> ls -1
common
contents
Example-Training-01.yml
images
templates
You will need to launch the container by:
/kpa/projects/<project name>
container's directory./tmp
) inside the/kpa/output
container's directory.--project <project name>
(in this example example
) and--yml <kpa document yaml>
(in this example Example-Training-01.yml
)Your command line will be something like this:
> docker run --rm \
-v $PWD:/kpa/projects/example \
-v /tmp:/kpa/output \
ghcr.io/mmul/kpa --project example --yml Example-Training-01.yml
After a really short time you should get:
Rendering example KPA project for Example-Training-01.yml file -> Completed.
The output files will be created in the output mapped directory (in this example
/tmp
):
> ls -1 /tmp/Example-Training-01.*
/tmp/Example-Training-01.agenda.md
/tmp/Example-Training-01.agenda.pdf
/tmp/Example-Training-01.md
/tmp/Example-Training-01.pdf
Note: in case of errors, it is possible to use the -v|--verbose
option to
get a more talkative output (in fact the ansbile-playbook
output).
The KPA container execution should produce these set of slides and agenda inside the mapped output directory:
Cover:
Chapter:
Slide:
Agenda:
The KPA container can be used interactively, and will give you an environment
with all the tools needed to generate both slides and agenda, but it is also
possible to use the kpa_generator
Ansible role locally. Check the
KPA manual commands document to learn how to use the tools
manually.
If you are interested in a deeper way of integrating KPA you can check the Using KPA in CI document to understand how to use KPA in both GitHub and GitLab CI workloads.
MIT
Raoul Scarazzini (rascasoft)