Show HN: MkSlides – Markdown to slides with a similar workflow to MkDocs
github.comAs a teacher, we keep our slides as markdown files in git repos and want to build these automatically so they can be viewed online (or offline if needed). To achieve this, I have created MkSlides. This tool converts all markdown in a folder to slides generated with Reveal.js. The workflow is very similar to MkDocs.
Install: `pip install mkslides`
Building slides: `mkslides build`
Live preview during editing: `mkslides serve`
Comparison with other tools like marp, slidev, ...:
- This tool is a single command and easy to integrate in CI/CD pipelines.
- It only needs Python.
- The workflow is also very similar to MkDocs, which makes it easy to combine the two in a single GitHub/GitLab repo.
- Generates an index landing page for multiple slideshows in a folder which is really convenient if you have e.g. a slideshow per chapter.
- It is lightweight.
- Everything is IaC.
Don't you find the linear format of slides built in this fashion very constraining?
Many excellent presenters use a slide as a 2D canvas on which text and images can be placed in arbitrary locations - whatever best helps get the ideas across to the audience. Is losing this feature worth the advantages of this tool?
I used DeckSet for years. I love this concept.
https://www.deckset.com
To answer your question directly, I am already all-in on Markdown and lightweight markup languages in general. Adopting such a thing is an exercise in a certain form of minimalism. In Markdown I can theoretically do anything by dropping into HTML, but the entire point (to me) is to focus on what I'm trying to write and not on every presentation and every slide being unique objects.
It's the same thing with my blog. I could use any number of tools that give me arbitrary control over text and images appearing wherever I want. But I choose not to want that in exchange for the simplicity and constraints guiding me to focus on what I'm trying to say rather than how I'm trying to say it.
I have found a local maximum for me, and tools like this are a good fit for that. You may be elsewhere enjoying a different kind of local maximum.
Also, what shipman05 said about version control and composition of text-based artefacts! It is nice to be able to interoperate with many text-based tools and scripts, although I rarely have needed the latter.
A text-based tool like this certainly puts a ceiling on presentation quality. Whether that really matters is situational. In most cases, content is more important than style once a certain threshold of "not hideous" is reached.
The same tradeoffs apply to a text-based diagram tool like mermaid.js vs more traditional diagramming tools like Miro.
My coworkers' Miro diagrams are prettier than my mermaid diagrams. But mine are composable and able to be versional controlled. I'm able to create complex diagrams many times faster using a text-based tool.
Ultimately, slides and diagrams are for conveying knowledge. If you're able to convey the same knowledge with significantly less effort, that outweighs the loss of "style points" in most situations (internal knowledge-transfer, meet-ups, etc).
Slight tangent counterpoint; sometimes conveying knowledge requires the prettier / flair of a miro/lucid/figma or even full infographic style solution.
I like md, and I like mermaid, and I like text / simple. But I know to help others, sometimes the visual medium and storytelling justify the alternatives.
What does this feature gain? You can only show one slide at a time anyways, and you can freely choose what slide comes next
Quarto also supports this: https://quarto.org/docs/presentations/
not sure if Quarto-specific but it lets you have Python code is slides too which is nice, i.e. can directly use visualization libraries
Does it support MkDocs extensions in any form? That's the first thing that came to mind for the name MkSlides. If not, that would be a great addition, although technically challenging.
No, MkSlides does not parse the markdown, but gives it as is to Reveal.js. Perhaps in the future we can mimick the API for MkDocs extensions, but it is out of scope for the moment.
Reveal.js vs Sli.dev seems like a toss up I am sure there are nuanced differences or maybe I am missing something obvious ?
There are some niche changes, but on the surface you can pick either one.
Why not Quarto? Genuinely curious.
I already use MkDocs, I don't use NodeJs. I looked for something in the Python ecosystem, but everything is JS. So i wanted to see if I could create it myself :)
I’ve used presenterm. Like it a lot.
https://mfontanini.github.io/presenterm/