Skip to content

Latest commit

 

History

History
188 lines (149 loc) · 6.7 KB

Commands.md

File metadata and controls

188 lines (149 loc) · 6.7 KB

KPA manual commands

If you don't want to use the KPA container to automate everything, and you have different needs, than this page explain how to manual run every step of the Knowledge Pods Approach.

Using the KPA container interactively

It is possible to launch the container interactively. You will need to map the directory containing your project and the output directory.

This means that if you are on your project directory (in a project called example) you will use this command line:

> docker run --rm -it --entrypoint /bin/bash \
  -v $PWD:/kpa/projects/example \
  -v /tmp:/kpa/output \
  ghcr.io/mmul-it/kpa
root@45a9a2efac84:/kpa#

Create the markdown files with kpa_generator.yml

The kpa_generator Ansible role is already available in the KPA container, but if you want to install it on your system you can use ansible-galaxy:

> ansible-galaxy install \
    -r playbooks/roles/requirements.yml \
    --roles-path ./playbooks/roles
Starting galaxy role install process
- downloading role 'kpa_generator', owned by mmul
- downloading role from https://github.com/mmul-it/kpa_generator/archive/main.tar.gz
- extracting mmul.kpa_generator to /home/rasca/Git/mmul-it/kpa/roles/mmul.kpa_generator
- mmul.kpa_generator (main) was installed successfully

Using the ansible-playbook command, the Ansible playbook named kpa_generator.yml under the playbooks folder, passing the KPA Project variables related to the common slides settings (-e @projects/example/common/settings.yml) and to the specific KPA document specification (-e @projects/example/Example-Training-01.yml) :

> ansible-playbook \
    -e @projects/example/common/settings.yml \
    -e @projects/example/Example-Training-01.yml \
    playbooks/kpa_generator.yml

The playbook tries to generate the pdf files for both slides and agenda if the two variables pandoc_agenda_output_pdf and marp_output_pdf are set, otherwise it will just generate the markdown files:

  • The Marp slides: Example-Training-01.md, as declared in the marp_output_file variable.
  • The schedule markdown: Example-Training-01.schedule.md, as declared in the pandoc_agenda_output_file variable.

For both variables check projects/example/settings.yml.

About executing the kpa_generator.yml Ansible playbook

The kpa_generator.yml Ansible playbook lives inside the playbooks folder.

Since this will be its working directory it will need access to both projects and output folder and this is the reason you will find two symbolic links pointing to your KPA projects directory and slides output directory:

> ls -la playbooks/
total 16
drwxrwxr-x 3 rasca rasca 4096 gen 27 15:26 .
drwxrwxr-x 7 rasca rasca 4096 gen 27 17:28 ..
-rw-rw-r-- 1 rasca rasca  139 gen 23 15:27 kpa_generator.yml
lrwxrwxrwx 1 rasca rasca   11 gen 27 15:26 projects -> ../projects
drwxrwxr-x 3 rasca rasca 4096 gen 27 16:02 roles
lrwxrwxrwx 1 rasca rasca    9 gen 27 15:26 output -> ../output

If you decide to store your projects in a different folder or you want a different output destination directory you can either change these symbolic links or use absolute paths for the kpa_project_dir and marp_output_markdown/pandoc_agenda_output_markdown Ansible variables.

Create the presentation from the Marp Markdown file

To get a presentation, i.e. in html format, with the Markdown file generated by the kpa_generator Ansible role you can use the Marp container, like this:

> docker run \
    --rm \
    -e LANG=$LANG \
    -e MARP_USER=$(id -u):$(id -g) \
    -v $PWD:/home/marp/app/ \
    marpteam/marp-cli \
      --html true \
      --theme ./projects/example/common/theme.css \
      output/
[  INFO ] Converting 1 markdown...

Or if you are in the KPA container, like this:

root@45a9a2efac84:/kpa# marp --html --theme projects/example/common/theme.css output/Example-Training-01.md  
[  INFO ] Converting 1 markdown...
[  INFO ] output/Example-Training-01.md => output/Example-Training-01.html

Marp supports exporting in pdf, html and ppt. You might needto remember the --allow-local-files when exporting into static files like pdf and ppt.

Create the presentation agenda from the agenda markdown file

It is possible to use pandoc to convert the generated Example-Training-01.agenda.md file into a pdf:

> pandoc --template=projects/example/common/example.tex \
    slides/Example-Training-01.schedule.md \
    -o slides/Example-Training-01.schedule.pdf

Check the projects/example/common/example.tex template that the pandoc is using is a simple one, but there's an infinite amount of possibilities with pandoc and texfiles.

About exporting with marp-cli

When exporting, the destination directory of your file should contain the images, .css files and so on, since it will process them "live". For this reason, you will find a symbolic link pointing to your KPA projects directory inside the slides output directory:

> ls -la slides/
total 3196
drwxrwxr-x 2 rasca rasca    4096 gen 17 18:37 .
drwxrwxr-x 7 rasca rasca    4096 gen 17 18:30 ..
lrwxrwxrwx 1 rasca rasca      10 gen 17 18:37 projects -> ../projects
-rw-r--r-- 1 rasca rasca  144942 gen 17 17:27 slides.html
-rw-rw-r-- 1 rasca rasca   11874 gen 17 17:27 slides.md
-rw-r--r-- 1 rasca rasca 3102777 gen 17 18:29 slides.pdf

If you want to change the destination of your .html slides, remember that you will need the projects directory (or a link) in there.

Themes

For the Example training, a custom css (check projects/example/theme.css) has been created to give a sample on how the look & feel might be changed.

The theme can be integrated with the various tools available for Marp:

  • Marp for VS Code extension, in the settings.json file:

    {
  "markdown.marp.themes": ["./projects/example/theme.css"],
  "markdown.marp.enableHtml": true
}

  • With the Marp CLI:

    > docker run \
  --rm \
  -e LANG=$LANG \
  -e MARP_USER=$(id -u):$(id -g) \
  -v $PWD:/home/marp/app/ \
  marpteam/marp-cli \
    --html true \
    --theme ./projects/example/theme.css \
    --pdf \
    --allow-local-files \
    slides/slides.md
[  INFO ] Converting 1 markdown...
[  WARN ] Insecure local file accessing is enabled for conversion from
          slides/Example-Training-01.md.
[  INFO ] slides/Example-Training-01.md => slides/Example-Training-01.pdf