展示 HN：MkSlides – Markdown 到幻灯片的转换，工作流程类似于 MkDocs

展示 HN：MkSlides – Markdown 到幻灯片的转换，工作流程类似于 MkDocs
Show HN: MkSlides – Markdown to slides with a similar workflow to MkDocs

原始链接: https://github.com/MartenBE/mkslides

## MkSlides：Markdown 到 Reveal.js 幻灯片 MkSlides 是一个静态站点生成器，它简化了使用 Reveal.js 框架从 Markdown 文件创建精美幻灯片的过程。它受到 MkDocs 和 reveal-md 的启发，通过单个 YAML 配置文件进行定制，从而简化了流程。您可以从单个 Markdown 文件或整个目录构建幻灯片，生成带有可选索引登陆页面的 HTML 幻灯片。部署方式灵活 – 可以在本地、Web 服务器上，或通过 CI/CD 管道进行部署。实时预览功能（使用 python-livereload）允许实时编辑和查看。 MkSlides 提供广泛的定制选项，包括主题、网站图标、CSS，以及对表情符号、Mermaid.js 和 PlantUML 的支持。配置通过 `mkslides.yml` 处理，可以使用 frontmatter 逐文件覆盖选项。关键命令包括 `mkslides build` 和 `mkslides serve`，用于构建和预览幻灯片。示例和进一步的文档请访问 [https://martenbe.github.io/mkslides](https://martenbe.github.io/mkslides) 和 [https://github.com/HoGentTIN/hogent-markdown-slides](https://github.com/HoGentTIN/hogent-markdown-slides)。

## MkSlides：轻松将 Markdown 转换为幻灯片 MkSlides 是一款新的 Python 工具，旨在从 Markdown 文件创建演示文稿，其设计灵感来自 MkDocs 工作流程。它由一位需要简化管理和部署来自 Git 仓库的幻灯片 Teachers 创建，可以将 Markdown 文件夹转换为由 Reveal.js 驱动的幻灯片演示文稿。主要功能包括简单的安装（`pip install mkslides`）、构建和实时预览命令（`mkslides build`，`mkslides serve`）以及易于集成到 CI/CD 管道中。它突出的特点是仅需要 Python，为多个演示文稿生成索引页面，并优先采用轻量级“基础设施即代码”方法。 Hacker News 讨论中提到了 Quarto 和 Presenterm 等替代方案，强调了其他基于 Markdown 的演示文稿创建选项。

原文

Use mkslides to easily turn Markdown files into beautiful slides using the power of Reveal.js!

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 and reveal-md.

Build static HTML slideshow files from Markdown files.
- Turn a single Markdown file into a HTML slideshow.
- Turn a folder with Markdown files into a collection of HTML slideshows with an index landing page.
Publish your slideshow(s) anywhere that static files can be served.
- Locally on your own device.
- On a web server.
- Deploy through CI/CD with GitHub/GitLab (like this repo!).
Preview your site as you work, thanks to python-livereload.
Use custom favicons, CSS themes, templates, ... if desired.
Support for emojis 😄 🎉 🚀 ✨ thanks to emoji
Depends heavily on integration/unit tests to prevent regressions.
And more!

Example slide from https://martenbe.github.io/mkslides with dracula theme:

Example index page from https://hogenttin.github.io/hogent-markdown-slides with HOGENT theme, custom title, and custom background logo:

Example output when building the website:

Example output when using live preview during editing:

Longer video:

Want more examples? An example repo with slides demonstrating all possibilities (Mermaid.js and PlantUML support, multicolumn slides, image resizing, ...) using Reveal.js with the HOGENT theme can be found at https://github.com/HoGentTIN/hogent-markdown-slides .

E.g. when your Markdown files are located in the slides/ folder:

If the slides folder doesn't exists, it will fallback to docs for backwards compatibility. If docs also doesn't exists, it will error.

E.g. when your Markdown files are located in the somefolder/ folder:

mkslides build somefolder/

E.g. when you have a single Markdown file called test.md:

⚠️ When you use a single file as PATH, only default static assets will be copied to the output folder. If you want to include images or other files, create a folder instead and pass that as PATH. Using a file as PATH is more meant for a quick slideshow in a pinch using only text.

The commands for live preview are very similar to creating a static website.

mkslides serve
mkslides serve somefolder/
mkslides serve test.md

⚠️ Also see the same remarks as with creating a static website.

mkslides build -h
mkslides serve -h

Just create a mkslides.yml. All options are optional, you only have to add what you want to change to mkslides.yml. Relative file paths are considered relative to the directory containing Markdown files (PATH).

Here's an example showcasing all possible options in the config file:

# Configuration for the generated index page
index:
    # Enables or disables the "Documentation built with MkSlides." footer:
    # boolean
    enable_footer: true

    # Favicon of the generated index page: file path or public url to favicon
    # file
    favicon: example-index-favicon.ico

    # Navigation section describing how to structure the slides on the index
    # page. This is similar to the `nav` option from MkDocs: list[any]
    nav:
        - Example: example1.md
        - "Example 2": somewhere/example1.md
        - example3.md
        - somewhere/example4.md
        - "More examples":
              - example5.md
              - "Much more examples":
                    - "Last example": somewhere/much/more/examples/example6.md

    # Title of the generated index page: string
    title: example-title

    # Jinja 2 template to generate index HTML: file path to Jinja2 file
    template: example.jinja

    # Theme of the generated index page: file path or public url to CSS file
    theme: example-index-theme.css

# Configuration for the slides
slides:
    # Charset of the slides: string
    # (see https://revealjs.com/markdown/#external-markdown)
    charset: utf-8

    # Favicon of the slides: file path or public url to favicon file
    favicon: example-slides-favicon.ico

    # Theme for syntax highlighting of code fragments on the slides: file path
    # to CSS file, public url to CSS file, or one of the highlight.js built-in
    # themes such as `monokai`, `obsidian`, `tokyo-night-dark`, `vs`, ...
    # (see https://highlightjs.org/examples)
    highlight_theme: example-slides-highlight-theme.css

    # Relative path to a python script containing a function
    # Callable[[str], str] named `preprocess`. Important: a relative file path
    # here is considered relative to the configuration file, as you probably
    # don't want to serve the python scripts.
    # For each Markdown file, the whole file content is given to the function as
    # a str. The returned string is then further processed as the Markdown to
    # give to Reveal.js
    preprocess_script: tests/test_preprocessors/replace_ats.py

    # Separator to determine notes of the slide: regexp
    # (see https://revealjs.com/markdown/#external-markdown)
    separator_notes: "^Notes?:"

    # Separator to determine end current/begin new vertical slide: regexp
    # (see https://revealjs.com/markdown/#external-markdown)
    separator_vertical: ^\s*-v-\s*$

    # Separator to determine end current/begin new slide: regexp
    # (see https://revealjs.com/markdown/#external-markdown)
    separator: ^\s*---\s*$

    # Jinja 2 template to generate index HTML: file path to Jinja2 file
    template: ./example.jinja

    # Theme of the slides: file path to CSS file, public url to CSS file, or one
    # of the reveal.js themes such as `black`, `white`, `league`, `solarized`,
    # `dracula`, ... (see https://revealjs.com/themes/)
    theme: example-slides-theme.css

    # Title of the slides. If this is set for a slide, it will be used for the
    # entry in the generated index HTML: string
    title: example-title

# Options to be passed to reveal.js: options in yaml format, they will be
# translated to JSON automatically (see https://revealjs.com/config/)
revealjs:
    height: 1080
    width: 1920
    transition: fade

    example_plugin:
        example_plugin_option_A: true
        example_plugin_option_B: qwerty

# Plugins or additional CSS/JavaScript files for the slides. These are given as
# a list.
plugins:
    # Name of the plugin (optional, see plugin README): plugin id string
    # (see https://revealjs.com/creating-plugins/#registering-a-plugin)
    - name: RevealExamplePlugin
      # List of CSS files of the plugin (optional, see plugin README):
      # public url to CSS file per entry
      extra_css:
          - https://cdn.jsdelivr.net/npm/reveal.js-example-pluging/example.min.css
      # List of JavaScript files of the plugin (optional, see plugin README):
      # public url to JavaScript file per entry
      extra_javascript:
          - https://cdn.jsdelivr.net/npm/reveal.js-example-pluging/example.min.js
    - name: RevealMermaid
      extra_javascript:
          - https://cdn.jsdelivr.net/npm/reveal.js-mermaid-plugin/plugin/mermaid/mermaid.min.js
    - extra_javascript:
          - https://cdn.jsdelivr.net/npm/reveal-plantuml/dist/reveal-plantuml.min.js

Default config (also used if no config file is present):

index:
    enable_footer: true
    template: assets/templates/index.html.jinja # Comes with the pip package
    title: Index
slides:
    highlight_theme: monokai
    template: assets/templates/slideshow.html.jinja # Comes with the pip package
    theme: black
revealjs:
    history: true
    slideNumber: c/t

It is also possible to override slides, revealjs, and plugins options on a per Markdown file base using it's frontmatter. Here, relative file paths are considered relative to the Markdown file itself.

---
slides:
    theme: solarized
    highlight_theme: vs
    separator: <!--s-->
    title: Frontmatter title.
revealjs:
    height: 1080
    width: 1920
    transition: zoom
---

# Slides with frontmatter

<!--s-->

## Lorem ipsum

Lorem 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.

<!--s-->

Notes:

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.
The precedence is frontmatter > mkslides.yml > defaults.

Usage: mkslides [OPTIONS] COMMAND [ARGS]...

  MkSlides - Slides with Markdown using the power of Reveal.js.

Options:
  -V, --version  Show the version and exit.
  -v, --verbose  Enable verbose output
  -h, --help     Show this message and exit.

Commands:
  build  Build the MkSlides documentation.
  serve  Run the builtin development server.

Usage: mkslides build [OPTIONS] [PATH]

  Build the MkSlides documentation.

  PATH is the path to the directory containing Markdown files. This argument
  is optional and will default to 'slides', or 'docs' if the first directory
  doesn't exist. If PATH is a single Markdown file or a directory containing a
  single Markdown file, it will always be processed into `index.html`
  regardless the name of the Markdown file.

Options:
  -f, --config-file FILENAME  Provide a specific MkSlides-Reveal config file.
  -d, --site-dir PATH         The directory to output the result of the slides
                              build. All files are removed from the site dir
                              before building.
  -s, --strict                Fail if a relative link cannot be resolved,
                              otherwise just print a warning.
  -h, --help                  Show this message and exit.

Usage: mkslides serve [OPTIONS] [PATH]

  Run the builtin development server.

  PATH is the path to the directory containing Markdown files. This argument
  is optional and will default to 'slides', or 'docs' if the first directory
  doesn't exist. If PATH is a single Markdown file or a directory containing a
  single Markdown file, it will always be processed into `index.html`
  regardless the name of the Markdown file.

Options:
  -f, --config-file FILENAME  Provide a specific MkSlides-Reveal config file.
  -s, --strict                Fail if a relative link cannot be resolved,
                              otherwise just print a warning.
  -a, --dev-addr <IP:PORT>    IP address and port to serve slides locally.
  -o, --open                  Open the website in a Web browser after the
                              initial build finishes.
  -h, --help                  Show this message and exit.

展示 HN：MkSlides – Markdown 到幻灯片的转换，工作流程类似于 MkDocs Show HN: MkSlides – Markdown to slides with a similar workflow to MkDocs

展示 HN：MkSlides – Markdown 到幻灯片的转换，工作流程类似于 MkDocs
Show HN: MkSlides – Markdown to slides with a similar workflow to MkDocs