README.md

kpa_generator

This role uses a KPA Project to generate Marp and Pandoc compatible Markdown files usable to create beautiful presentations in html, pdf and ppt format with their agenda. By default it automates the creation of a pdf slides set and their pdf agenda.

Role Variables

To get a minimal slides set you can rely on the defaults, and then change everything you need to customize your result:

---

################
# KPA settings #
################

# Location of your KPA project
kpa_project_dir: "{{ playbook_dir }}"

# Slide set title
kpa_title: "My slides set"

# Author & Copyright info
kpa_author: 'My author'
kpa_copyright: '© 2023 My copyright'

###################
# Pandoc settings #
###################

# Pandoc Agenda Markedown output files destination
pandoc_agenda_output_markdown: "{{ kpa_project_dir }}/slides.agenda.md"
pandoc_agenda_output_pdf: "{{ kpa_project_dir }}/slides.agenda.pdf"

###################
# Marp settings   #
###################

# Marp Markdown output files destination
marp_output_markdown: "{{ kpa_project_dir }}/slides.md"
marp_output_pdf: "{{ kpa_project_dir }}/slides.pdf"
# Set marp_output_pptx to generate a PowerPoint compatible file
# marp_output_pptx: "{{ kpa_project_dir }}/slides.pptx"

# Marp theme (default, gaia, uncover or a custom theme)
marp_theme: default

# Add slide number
marp_paginate: false

# Cover slide details (set cover: true on kpa_slides entry)
# marp_cover_background_image to pass an image path/url
marp_cover_background_color: '#FFCCE1'
marp_cover_template: "templates/cover.md.j2"
marp_cover_header: null
marp_cover_footer: "**{{ kpa_author }}** | _{{ kpa_copyright }}_"

# Chapter slide details
marp_chapter_background_color: '#FAFFC7'
marp_chapter_template: "templates/chapter.md.j2"

# Common slides background color
# marp_background_image to use an image path/url
marp_background_color: '#D7EEFF'
marp_header: true  # Will show {{ kpa_title }} | {{ kpa_author }}
marp_footer: true  # Will show {{ slide.chapter }} | {{ slide.title }}

##############
# KPA slides #
##############

# Slide list, this is what KPA (https://github.com/mmul-it/kpa) is meant for
kpa_slides:
  # Cover slide (doesn't need content:)
  - cover: true
    title: "{{ kpa_title }}"
    subtitle: "DAY ONE"
  # First Knowledge Pod
  - chapter: 'DAY ONE - First Knowledge Pod'
    title: 'Topic 1'
    chapter_header: "A custom header for this specific chapter ONE"
    content: "{{ kpa_project_dir }}/contents/knowledge-pod-1.md"
  # Second Knowledge Pod
  - chapter: 'DAY ONE - Second Knowledge Pod'
    title: 'Topic 2'
    chapter_footer: "A custom footer for this specific chapter TWO"
    content: "{{ kpa_project_dir }}/contents/knowledge-pod-2.md"

For example, to generate a pptx output file just set the marp_output_pptx variable, and the playbook will also run marp with the option to generate a Microsoft PowerPoint compatible file.

Example Playbook

To test this role and generate a simple Markdown usable with Marp, just use the tests/kpa_generator.yml playbook as it is:

---

- hosts: localhost
  gather_facts: false
  connection: local
  name: Use a KPA Project to create a Marp Markdown compatible file
  roles:
    - role: ../..

And execute it using ansible-playbook:

> ansible-playbook tests/kpa_generator.yml
PLAY [Use a KPA Project to create Marp & Pandoc markdown and slide decks] ******

TASK [../.. : Create Marp slides markdown] *************************************
changed: [localhost]

TASK [../.. : Create Pandoc agenda markdown] ***********************************
changed: [localhost]

TASK [../.. : Generate pdf slides with Marp] ***********************************
changed: [localhost]

TASK [../.. : Generate pptx slides with Marp] **********************************
skipping: [localhost]

TASK [../.. : Generate pdf agenda with Pandoc] *********************************
changed: [localhost]

PLAY RECAP *********************************************************************
localhost                  : ok=4    changed=4    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0

This will generate two couples of files:

1. A file named tests/slides.md that is process by marp, to get tests/slides.pdf.

   When the marp executable is available on the system the process is automatic, and is the equivalent of this manual operation:

   > docker run \
     --rm \
     -e MARP_USER=1000:1000 \
     -e LANG=en_US.UTF-8 \
     -v $PWD:/home/marp/app/ \
     marpteam/marp-cli --html --pdf --allow-local-files tests/slides.md
   [  INFO ] Converting 1 markdown...
   [  WARN ] Insecure local file accessing is enabled for conversion from
             tests/slides.md.
   [  INFO ] tests/slides.md => tests/slides.pdf

2. A file named tests/slides.agenda.md that is processed by pandoc to get tests/slides.agenda.pdf.

   When the pandoc executable is available on the system the process is automatic, and is the equivalent of this manual operation:

   > pandoc tests/slides.agenda.md -o tests/slides.agenda.pdf

   Note: pandoc supports templates that can be used to customize the pdf.

The full environment is available inside the KPA container at quay.io.

For details about using this role in the training and documentation context, have a look at the KPA GitHub project page.

License

MIT

Author Information

Raoul Scarazzini (rascasoft)