{"id":15017432,"url":"https://github.com/MartenBE/mkslides","last_synced_at":"2025-09-25T21:30:48.678Z","repository":{"id":255461088,"uuid":"849785913","full_name":"MartenBE/mkslides","owner":"MartenBE","description":"Use mkslides to easily turn markdown files into beautiful slides using the power of Reveal.js!","archived":false,"fork":false,"pushed_at":"2025-01-12T14:47:05.000Z","size":5923,"stargazers_count":42,"open_issues_count":3,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-12T15:11:52.046Z","etag":null,"topics":["markdown","markdown-to-html","mkdocs","site-generator","slides","slideshow"],"latest_commit_sha":null,"homepage":"https://martenbe.github.io/mkslides/","language":"Python","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/MartenBE.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2024-08-30T08:42:14.000Z","updated_at":"2025-01-12T14:47:09.000Z","dependencies_parsed_at":"2024-09-21T15:37:48.082Z","dependency_job_id":"19f385aa-7fd1-4923-8ebb-5018ff69dc49","html_url":"https://github.com/MartenBE/mkslides","commit_stats":{"total_commits":134,"total_committers":3,"mean_commits":"44.666666666666664","dds":0.07462686567164178,"last_synced_commit":"bc5d63853e151312676c3f603d5b5cd779cbfa0a"},"previous_names":["martenbe/mkslides-reveal","martenbe/mkslides"],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MartenBE%2Fmkslides","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MartenBE%2Fmkslides/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MartenBE%2Fmkslides/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MartenBE%2Fmkslides/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MartenBE","download_url":"https://codeload.github.com/MartenBE/mkslides/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234251199,"owners_count":18803013,"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":["markdown","markdown-to-html","mkdocs","site-generator","slides","slideshow"],"created_at":"2024-09-24T19:50:27.450Z","updated_at":"2025-09-25T21:30:48.672Z","avatar_url":"https://github.com/MartenBE.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MkSlides\n\n\u003e Use `mkslides` to easily turn markdown files into beautiful slides using the power of [Reveal.js](https://revealjs.com/)!\n\n[![PyPI](https://img.shields.io/pypi/v/mkslides)](https://pypi.org/project/mkslides/)\n[![test-deploy.yml](https://github.com/MartenBE/mkslides/actions/workflows/test-deploy.yml/badge.svg?branch=main)](https://github.com/MartenBE/mkslides/actions)\n\n[MkSlides](https://pypi.org/project/mkslides/) is a static site generator that's geared towards building slideshows. Slideshow source files are written in Markdown, and configured with a single YAML configuration file. The workflow and commands are heavily inspired by [MkDocs](https://pypi.org/project/mkdocs/) and [reveal-md](https://github.com/webpro/reveal-md).\n\n## Features\n\n- Build static HTML slideshow files from Markdown files.\n    - Turn a single Markdown file into a HTML slideshow.\n    - Turn a folder with Markdown files into a collection of HTML slideshows.\n- Publish your slideshow(s) anywhere that static files can be served.\n    - Locally\n    - On a webserver\n    - Deploy through CI/CD with GitHub/GitLab (like this repo!)\n- Preview your site as you work, thanks to [python-livereload](https://pypi.org/project/livereload/).\n- Use custom favicons, CSS themes, templates, ... if desired.\n- Support for emojis :smile: :tada: :rocket: :sparkles: thanks to [emoji](https://github.com/carpedm20/emoji/)\n- Depends heavily on integration/unit tests to prevent regressions.\n- And more!\n\n## Example\n\n[demo.webm](https://github.com/user-attachments/assets/b594170e-a103-4643-88db-b32437426e77)\n\n[Youtube link](https://youtu.be/RdyRe3JZC7Q) in case you want to look at 2x speed.\n\nWant more examples? An example repo with [slides](https://hogenttin.github.io/hogent-markdown-slides/) demonstrating all possibilities ([Mermaid.js](https://mermaid.js.org/) and [PlantUML](https://plantuml.com/) support, multicolumn slides, image resizing, ...) using Reveal.js with the [HOGENT](https://hogent.be/) theme can be found at https://github.com/HoGentTIN/hogent-markdown-slides .\n\n## Installation\n\n```bash\npip install mkslides\n```\n\n## Create static site\n\nE.g. when your Markdown files are located in the `docs/` folder:\n\n```bash\nmkslides build docs/\n```\n\nE.g. when you have a single Markdown file called `test.md`:\n\n```bash\nmkslides build test.md\n```\n\n## Live preview\n\n```bash\nmkslides serve docs/\n```\n\n```bash\nmkslides serve test.md\n```\n\n# Need help or want to know more?\n\n## Commands\n\n```bash\nmkslides build -h\nmkslides serve -h\n```\n\n## Configuration\n\nJust create a `mkslides.yml`. All options are optional, you only have to add what you want to change to `mkslides.yml`.\n\nHere's an example showcasing all possible options in the config file:\n\n```yml\n# Configuration for the generated index page\nindex:\n    # Favicon of the generated index page: file path or public url to favicon\n    # file\n    favicon: ./example-index-favicon.ico\n\n    # Jinja 2 template to generate index HTML: file path to Jinja2 file\n    template: ./example.jinja\n\n    # Theme of the generated index page: file path or public url to CSS file\n    theme: example-index-theme.css\n\n    # Title of the generated index page: string\n    title: example-title\n\n# Configuration for the slides\nslides:\n    # Charset of the slides: string\n    # (see https://revealjs.com/markdown/#external-markdown)\n    charset: utf-8\n\n    # Favicon of the slides: file path or public url to favicon file\n    favicon: ./example-slides-favicon.ico\n\n    # Theme for syntax highlighting of code fragments on the slides: file path\n    # to CSS file, public url to CSS file, or one of the highlight.js built-in\n    # themes such as `monokai`, `obsidian`, `tokyo-night-dark`, `vs`, ...\n    # (see https://highlightjs.org/examples)\n    highlight_theme: example-slides-highlight-theme.css\n\n    # Relative path to a python script containing a function\n    # Callable[[str], str] named `preprocess`. For each Markdown file, the whole\n    # file content is given to the function as a str. The returned string is\n    # then further processed as the markdown to give to Reveal.js\n    preprocess_script: tests/test_preprocessors/replace_ats.py\n\n    # Separator to determine notes of the slide: regexp\n    # (see https://revealjs.com/markdown/#external-markdown)\n    separator_notes: \"^Notes?:\"\n\n    # Separator to determine end current/begin new vertical slide: regexp\n    # (see https://revealjs.com/markdown/#external-markdown)\n    separator_vertical: ^\\s*-v-\\s*$\n\n    # Separator to determine end current/begin new slide: regexp\n    # (see https://revealjs.com/markdown/#external-markdown)\n    separator: ^\\s*---\\s*$\n\n    # Jinja 2 template to generate index HTML: file path to Jinja2 file\n    template: ./example.jinja\n\n    # Theme of the slides: file path to CSS file, public url to CSS file, or one\n    # of the reveal.js themes such as `black`, `white`, `league`, `solarized`,\n    # `dracula`, ... (see https://revealjs.com/themes/)\n    theme: example-slides-theme.css\n\n# Options to be passed to reveal.js: options in yaml format, they will be\n# translated to JSON automatically (see https://revealjs.com/config/)\nrevealjs:\n    height: 1080\n    width: 1920\n    transition: fade\n\n    example_plugin:\n        example_plugin_option_A: true\n        example_plugin_option_B: qwerty\n\n# Plugins or additional CSS/JavaScript files for the slides. These are given as\n# a list.\nplugins:\n    # Name of the plugin (optional, see plugin README): plugin id string\n    # (see https://revealjs.com/creating-plugins/#registering-a-plugin)\n    - name: RevealExamplePlugin\n      # List of CSS files of the plugin (optional, see plugin README):\n      # public url to CSS file per entry\n      extra_css:\n          - https://cdn.jsdelivr.net/npm/reveal.js-example-pluging/example.min.css\n      # List of JavaScript files of the plugin (optional, see plugin README):\n      # public url to JavaScript file per entry\n      extra_javascript:\n          - https://cdn.jsdelivr.net/npm/reveal.js-example-pluging/example.min.js\n    - name: RevealMermaid\n      extra_javascript:\n          - https://cdn.jsdelivr.net/npm/reveal.js-mermaid-plugin/plugin/mermaid/mermaid.min.js\n    - extra_javascript:\n          - https://cdn.jsdelivr.net/npm/reveal-plantuml/dist/reveal-plantuml.min.js\n```\n\nDefault config (also used if no config file is present):\n\n```yml\nindex:\n    title: Index\n    template: assets/templates/index.html.jinja # Comes with the pip package\nslides:\n    theme: black\n    highlight_theme: monokai\n    template: assets/templates/slideshow.html.jinja # Comes with the pip package\nrevealjs:\n    history: true\n    slideNumber: c/t\n```\n\nIt is also possible to override `slides`, `revealjs`, and `plugins` options on a per Markdown file base using it's frontmatter:\n\n```md\n---\ntitle: frontmatter title\nslides:\n    theme: solarized\n    highlight_theme: vs\n    separator: \u003c!--s--\u003e\nrevealjs:\n    height: 1080\n    width: 1920\n    transition: zoom\n---\n\n# Slides with frontmatter\n\n\u003c!--s--\u003e\n\n## Lorem ipsum\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n\n\u003c!--s--\u003e\n```\n\nNotes:\n\n- `title` here is a frontmatter-only available option to set the title of this slideshow in the generated index page. This option is not available in `mkslides.yml`.\n- The precedence is frontmatter \u003e `mkslides.yml` \u003e defaults.\n\n## Full help\n\n\u003c!-- output-no-command --\u003e\n```text\nUsage: mkslides [OPTIONS] COMMAND [ARGS]...\n\n  MkSlides - Slides with Markdown using the power of Reveal.js.\n\nOptions:\n  -V, --version  Show the version and exit.\n  -v, --verbose  Enable verbose output\n  -h, --help     Show this message and exit.\n\nCommands:\n  build  Build the MkDocs documentation.\n  serve  Run the builtin development server.\n\n```\n\u003c!-- /output-no-command --\u003e\n\n\u003c!-- output-build --\u003e\n```text\nUsage: mkslides build [OPTIONS] FILENAME|PATH\n\n  Build the MkDocs documentation.\n\n  FILENAME|PATH is the path to the Markdown file, or the directory containing\n  Markdown files.\n\nOptions:\n  -f, --config-file FILENAME  Provide a specific MkSlides-Reveal config file.\n  -d, --site-dir PATH         The directory to output the result of the slides\n                              build. All files are removed from the site dir\n                              before building.\n  -s, --strict                Fail if a relative link cannot be resolved,\n                              otherwise just print a warning.\n  -h, --help                  Show this message and exit.\n\n```\n\u003c!-- /output-build --\u003e\n\n\u003c!-- output-serve --\u003e\n```text\nUsage: mkslides serve [OPTIONS] FILENAME|PATH\n\n  Run the builtin development server.\n\n  FILENAME|PATH is the path to the Markdown file, or the directory containing\n  Markdown files.\n\nOptions:\n  -f, --config-file FILENAME  Provide a specific MkSlides-Reveal config file.\n  -s, --strict                Fail if a relative link cannot be resolved,\n                              otherwise just print a warning.\n  -a, --dev-addr \u003cIP:PORT\u003e    IP address and port to serve slides locally.\n  -o, --open                  Open the website in a Web browser after the\n                              initial build finishes.\n  -h, --help                  Show this message and exit.\n\n```\n\u003c!-- /output-serve --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMartenBE%2Fmkslides","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMartenBE%2Fmkslides","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMartenBE%2Fmkslides/lists"}