{"id":14984482,"url":"https://github.com/mmul-it/kpa","last_synced_at":"2025-10-27T01:11:04.464Z","repository":{"id":156445870,"uuid":"589981615","full_name":"mmul-it/kpa","owner":"mmul-it","description":"KPA - Knowledge Pods Approach","archived":false,"fork":false,"pushed_at":"2025-01-22T16:30:22.000Z","size":6771,"stargazers_count":58,"open_issues_count":3,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-31T03:11:13.392Z","etag":null,"topics":["ansible","ansible-playbook","ansible-role","container-image","docker","documentation","knowledge-as-a-service","kpa","markdown","marp","pandoc","pdf","slides","standard"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mmul-it.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-17T11:52:29.000Z","updated_at":"2025-03-01T06:28:46.000Z","dependencies_parsed_at":"2023-10-15T03:41:33.486Z","dependency_job_id":"a294a352-3317-46ff-ae60-b4cc45affe69","html_url":"https://github.com/mmul-it/kpa","commit_stats":{"total_commits":72,"total_committers":2,"mean_commits":36.0,"dds":0.01388888888888884,"last_synced_commit":"87f5d07234e10f06a61bdbbc4e86032976d7e9e6"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmul-it%2Fkpa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmul-it%2Fkpa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmul-it%2Fkpa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmul-it%2Fkpa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mmul-it","download_url":"https://codeload.github.com/mmul-it/kpa/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252771760,"owners_count":21801775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","ansible-playbook","ansible-role","container-image","docker","documentation","knowledge-as-a-service","kpa","markdown","marp","pandoc","pdf","slides","standard"],"created_at":"2024-09-24T14:09:08.569Z","updated_at":"2025-10-27T01:10:59.434Z","avatar_url":"https://github.com/mmul-it.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ![KPA - The Knowledge Pods Approach](./images/kpa-github-header.png)\n\n[![GitHub Actions CI](https://github.com/mmul-it/kpa/actions/workflows/main.yml/badge.svg?event=push)](https://github.com/mmul-it/kpa/actions/workflows/main.yml)\n\nThis repository defines the **Knowledge Pods Approach** (**KPA**), an agile way\nto create, maintain and evolve training materials and presentations using\nstandard [markdown](https://en.wikipedia.org/wiki/Markdown) files to create\nbeautiful slide sets and agendas.\n\n## What is KPA\n\nThe **Knowledge Pods Approach (KPA)** is a method for creating training\nmaterials, presentations and documentation that separates the content creation\n(*the knowledge*) from their presentation (*the files*, i.e. pdf, ppt and html).\n\n**KPA** relies on the standard markdown file format, which means that there will\nbe no need to rely on proprietary tools and formats to create contents.\n\n**KPA** helps to concentrate on what matters most: the knowledge.\n\n**KPA** is at the same time:\n\n- The definition of an approach, described in this page.\n- A container named **kpa** available on the main public container registries:\n  - [GitHub Container Registry](https://ghcr.io/mmul-it/kpa).\n  - [Quay](https://quay.io/repository/mmul/kpa).\n  - [Docker Hub](https://hub.docker.com/r/mmul/kpa).\n- An Ansible role named **kpa_generator** available in\n  [Ansible Galaxy](https://galaxy.ansible.com/mmul/kpa_generator).\n\n## What is a KPA project\n\nA **KPA project** is a set of variables and markdown files that are used by the\nAnsible role named [kpa_generator](https://github.com/mmul-it/kpa_generator) to\nautomate the creation of a single combined markdown file that can be processed\nby [Marp (Markdown Presentation Ecosystem)](https://marp.app/#get-started) to\nobtain a set of slides in the usual presentation formats like **html**, **pdf**\nand **ppt**.\nThe **kpa_generator** Ansible role generates also an agenda markdown that is\nconverted to a PDF using the [Pandoc](https://pandoc.org/) tool.\n\n**KPA** makes it possible to control all the knowledge in a standard and \"edit\nfrom everywhere\" way, making it easy to compose and mix the set of topics you\nwant to include into the training, by creating sequences of **Knowledge Pods**\n(**KP**).\n\n## What is a Knowledge Pod\n\nA **Knowledge Pod** (**KP**) is the smallest part you can split a section of a\ntraining or of a presentation.\n\nYou can imagine it as a chapter. For example, if you need to deliver a training\nnamed \"**How to use my technology**\" in which you'll have to cover an\n**introduction** to your technology, the **prerequisites**, the **installation**\nand finally **day 0 operation**, then each one of these chapters would be a\nKnowledge Pod, like:\n\n- *Introduction.md*\n- *Prerequisites.md*\n- *Installation.md*\n- *Day-0-operations.md*\n\nA **Knowledge Pod** should have, uniformly, the same duration (say one hour), so\nthat it will be easy to compose a training by picking the needed KPs.\n\nEach section of a **Knowledge Pod**, say a paragraph, is separated from the\nother with the `---` Markdown element, which represents a new slide.\n\n## What are the benefits of adopting KPA\n\nThere are several benefits using KPA:\n\n- **Concentrate \u003cu\u003ejust\u003c/u\u003e on the contents**: once you have defined your\n  project, you don't need to care about anything but writing Knowledge Pods.\n  No need to manually syntax highlight your code blocks, no need to adapt text,\n  no need to duplicate your slide to modify just a simple sentence.\n  Just write your Knowledge Pods in Markdown and you're good to go.\n- **Compose training and presentations \u003cu\u003edynamically\u003c/u\u003e**: no more Power Point\n  slides cut and paste. You can combine your Knowledge Pods in the way that fits\n  your needs, creating as many variants of your training and presentations as\n  you need.\n- **Have the same look \u0026 feel for \u003cu\u003eevery\u003c/u\u003e training or presentation**: no\n  more \"*Ok, now you need to apply this new slide format to all our 100\n  presentations*\". You will define your project look \u0026 feel one time and it will\n  be applied everywhere, always the same way.\n- **Use a \u003cu\u003estandard\u003c/u\u003e and \u003cu\u003ereusable\u003c/u\u003e format**: the same documentation\n  you will produce with KPA could be used wherever you want because it's\n  markdown, which is a standard, and you will be able to write your own tool to\n  manage your **Knowledge Pods**.\n- **Keep everything versioned and \u003cu\u003ein order\u003c/u\u003e**: once you'll store your KPA\n  projects in a Git repository, you'll get versioning, monitoring of the changes\n  and your entire knowledge in one traceable place.\n- **Let everyone \u003cu\u003edo their job\u003c/u\u003e**: Markdown is simple to the point that\n  even non-technical people can edit Knowledge Pods and this allows for everyone\n  to do their job: graphics can work on the themes, instructors can write the\n  contents and you, the **KPA master ©**, will put everything together.\n\n## How to create a KPA project\n\nAfter cloning this repository:\n\n```bash\n\u003e git clone https://github.com/mmul-it/kpa.git\nCloning into 'kpa'...\nremote: Enumerating objects: 125, done.\nremote: Counting objects: 100% (125/125), done.\nremote: Compressing objects: 100% (59/59), done.\nremote: Total 125 (delta 51), reused 114 (delta 43), pack-reused 0\nReceiving objects: 100% (125/125), 3.88 MiB | 3.38 MiB/s, done.\nResolving deltas: 100% (51/51), done.\n\n\u003e cd kpa\n```\n\nYou'll see a `projects` directory, which is meant to contain all your KPA\nprojects. You can use `example` project as your starting point.\n\nThis is the structure of a **KPA project**:\n\n```console\nprojects/example/\n├── common\n│   ├── settings.yml\n│   ├── example.tex\n│   └── theme.css\n├── images\n│   ├── chapter-background.png\n│   ├── cover-background.png\n│   ├── logo.png\n│   └── slide-background.png\n├── templates\n│   ├── chapter.md.j2\n│   └── cover.md.j2\n├── contents\n│   ├── Topic-10.md\n│   ├── ...\n│   └── Topic-18.md\n└── Example-Training-01.yml\n```\n\nWhere:\n\n- [common](projects/example/common): is the home for shared\n  training/presentation files:\n  - [theme.css](projects/example/common/theme.css) is the css theme file that\n    overrides Marp's default theme. This is not needed, you can use a\n    [predefined Marp theme](https://github.com/marp-team/marp-core/tree/main/themes).\n  - [example.tex](projects/example/common/example.tex) is the Pandoc texfile\n    template. This is not *strictly* needed, but to get the best from the\n    generated agenda pdf a Pandoc template is more than reasonable.\n  - [settings.yml](projects/example/common/settings.yml) **is mandatory** and\n    contains the general presentation parameters that will override role's\n    defaults:\n\n    ```yaml\n    ---\n\n    # KPA\n    kpa_project_dir: 'projects/example'\n    kpa_author: 'Raoul Scarazzini'\n    kpa_copyright: '© 2023 MiaMammaUsaLinux.org'\n\n    # Pandoc\n    pandoc_agenda_template_file: \"{{ kpa_project_dir }}/common/example.tex\"\n    pandoc_agenda_background_image: \"{{ kpa_project_dir }}/images/schedule-background.png\"\n    pandoc_agenda_header_includes:\n      - '\\usepackage{booktabs}'\n      - '\\usepackage{longtable}'\n      - '\\usepackage{array}'\n      - '\\usepackage{multirow}'\n      - '\\usepackage{wrapfig}'\n      - '\\usepackage{float}'\n      - '\\usepackage{colortbl}'\n      - '\\usepackage{pdflscape}'\n      - '\\usepackage{tabu}'\n      - '\\usepackage{threeparttable}'\n      - '\\usepackage{threeparttablex}'\n      - '\\usepackage[normalem]{ulem}'\n      - '\\usepackage{makecell}'\n\n    # Marp\n    marp_theme: example\n    marp_theme_file: \"{{ kpa_project_dir }}/common/theme.css\"\n    marp_background_color: #ffffff\n    marp_background_image: \"{{ kpa_project_dir }}/images/slide-background.png\"\n    marp_paginate: true\n    marp_cover_template: \"{{ kpa_project_dir }}/templates/cover.md.j2\"\n    marp_cover_image: \"{{ kpa_project_dir }}/images/cover-image.png\"\n    marp_cover_logo: \"{{ kpa_project_dir }}/images/logo.png\"\n    marp_cover_background_image: \"{{ kpa_project_dir }}/images/cover-background.png\"\n    marp_chapter_template: \"{{ kpa_project_dir }}/templates/chapter.md.j2\"\n    marp_chapter_background_image: \"{{ kpa_project_dir }}/images/chapter-background.png\"\n    ```\n\n- [images](projects/example/images/) contains backgrounds, logos and all the\n  useful graphics elements for the slides.\n- [templates](projects/example/templates/) contains the templates for the\n  special slides that will be processed by Ansible. These templates will parse\n  the variables, to be reusable. For example, the [chapter.md.j2](projects/example/templates/chapter.md.j2)\n  contains the layout for the slide that will be shown at the beginning of each\n  KP/Chapter:\n\n  ```markdown\n  ---\n\n  \u003c!-- _backgroundImage: url({{ marp_chapter_background_image }}) --\u003e\n\n  # \u003cspan class=\"txt-yellow\"\u003e{{ slide.title }}\u003c/span\u003e\n\n  \u003cspan class=\"txt-yellow\"\u003e{{ slide.chapter }}\u003c/span\u003e\n  ```\n\n  The variables used in this file can be declared globally (like\n  `marp_chapter_backgroundImage`, see [slides-settings.yml](projects/example/slides-settings.yml))\n   or specifically (like `slide.title`, see [Example-Training-01.yml](projects/example/Example-Training-01.yml)).\n- [contents](projects/example/contents/) contains the **Knowledge Pods** in the\n  [Marp Markdown compatible format](https://marpit.marp.app/markdown) (The main\n  rule: `---` is the beginning of a new slide).\n- [Example-Training-01.yml](projects/example/Example-Training-01.yml) is the\n  slides set declaration, it contains the structure of the document, in a list\n  element:\n\n  ```yaml\n  ---\n\n  # KPA\n  kpa_title: \"My spectacular course\"\n  kpa_contents: \"{{ kpa_project_dir }}/contents\"\n  kpa_slides:\n    # DAY 1\n    - cover: true\n      title: \"{{ kpa_title }}\"\n      subtitle: \"DAY ONE\"\n    - chapter: 'DAY ONE - PART ONE'\n      title: 'Topic 1'\n      content: \"{{ kpa_contents }}/Topic-1.md\"\n    - chapter: 'DAY ONE - PART TWO'\n      title: 'Topic 2'\n      content: \"{{ kpa_contents }}/Topic-2.md\"\n      ...\n      ...\n    # Day 2\n    - cover: true\n      title: \"{{ kpa_title }}\"\n      subtitle: \"DAY TWO\"\n    - chapter: 'DAY TWO - PART SEVEN'\n      title: 'Topic 7'\n      content: \"{{ kpa_contents }}/Topic-7.md\"\n      ...\n      ...\n    # Day 3\n    - cover: true\n      title: \"{{ kpa_title }}\"\n      subtitle: \"DAY THREE\"\n    - chapter: 'DAY THREE - PART THIRTEEN'\n      title: 'Topic 13'\n      content: \"{{ kpa_contents }}/Topic-13.md\"\n      ...\n      ...\n    - chapter: 'DAY THREE - PART EIGHTEEN'\n      title: 'Topic 18'\n      content: \"{{ kpa_contents }}/Topic-18.md\"\n\n  # Output\n  output_file: \"slides/Example-Training-01\"\n  schedule_output_file: \"{{ output_file }}.schedule.md\"\n  marp_output_file: \"{{ output_file }}.md\"\n  ```\n\n## How to use the KPA container\n\nKPA comes with a handy container that can be used to automate the creation of\nboth the slides and the agenda PDF files.\n\nOnce you have a local project in place:\n\n```console\n\u003e ls -1\ncommon\ncontents\nExample-Training-01.yml\nimages\ntemplates\n```\n\nYou will need to launch the container by:\n\n- Mapping the project directory as a volume inside the\n  `/kpa/projects/\u003cproject name\u003e` container's directory.\n- Mapping the output directory (in this example `/tmp`) inside the\n  `/kpa/output` container's directory.\n- Pass the `--project \u003cproject name\u003e` (in this example `example`) and\n  `--yml \u003ckpa document yaml\u003e` (in this example `Example-Training-01.yml`)\n  options.\n\nYour command line will be something like this:\n\n```console\n\u003e docker run --rm \\\n  -v $PWD:/kpa/projects/example \\\n  -v /tmp:/kpa/output \\\n  ghcr.io/mmul/kpa --project example --yml Example-Training-01.yml\n```\n\nAfter a really short time you should get:\n\n```console\nRendering example KPA project for Example-Training-01.yml file -\u003e Completed.\n```\n\nThe output files will be created in the output mapped directory (in this example\n`/tmp`):\n\n```console\n\u003e ls -1 /tmp/Example-Training-01.*\n/tmp/Example-Training-01.agenda.md\n/tmp/Example-Training-01.agenda.pdf\n/tmp/Example-Training-01.md\n/tmp/Example-Training-01.pdf\n```\n\n**Note**: in case of errors, it is possible to use the `-v|--verbose` option to\nget a more talkative output (in fact the `ansbile-playbook` output).\n\n### Results\n\nThe KPA container execution should produce these set of slides and agenda inside\nthe mapped output directory:\n\n- Cover:\n\n  ![images/slide-cover.png](images/slide-cover.png)\n\n- Chapter:\n\n  ![](images/slide-chapter.png)\n\n- Slide:\n\n  ![](images/slide.png)\n\n- Agenda:\n\n  ![](images/schedule.png)\n\n### How to use KPA manually and in CI\n\nThe KPA container can be used interactively, and will give you an environment\nwith all the tools needed to generate both slides and agenda, but it is also\npossible to use the `kpa_generator` Ansible role locally. Check the\n[KPA manual commands](Commands.md) document to learn how to use the tools\nmanually.\n\nIf you are interested in a deeper way of integrating KPA you can check the\n[Using KPA in CI](CI.md) document to understand how to use KPA in both GitHub\nand GitLab CI workloads.\n\n## License\n\nMIT\n\n## Author Information\n\nRaoul Scarazzini ([rascasoft](https://github.com/rascasoft))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmul-it%2Fkpa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmmul-it%2Fkpa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmul-it%2Fkpa/lists"}