Make it available as Docker image

[jurgenhaas]

Installation, setup and usage could be simplified by making this project available as a Docker image. I'd be willing to contribute the Dockerfile if you'd agree to such an approach.

[qx-775]

I agree please please provide a Docker container. It would be much appreciated. I tried setting up mdshow on both Arch Linux and Debian and both had lots of problems with wrong commands and other errors that I have not resolved so far. The setup does not work correctly on Debian.

Also I really like this tool, I too believe in quickly making beautiful presentations in a single markdown file. So thank you.

[jceb]

Yes, the docker image has been on my mind in the past in order to alleviate some of the installation troubles. However, Docker adds other troubles ;-) One trouble is that Docker creates files as root by default, another is that inotify doesn't work and so watching file changes becomes a little tricky. Not sure how gulp deals with it.

Before you start contributing, take a look at my work at the markdeck project. There, I built a docker-compose solution to handle the root issue.

[jurgenhaas]

With regard to the two specific concerns, I'd say

• files created as root: that depends on how the containers gets started, there's a lot of options around
• gulp and recognizing changes: I'm using this a lot in a gulp environment to compile sass into css when any file changes, don't see any issues with that

I will give this a try, but the next conference where I need slides is only 8 days ahead, so I won't be able to spend time is this before that.

[jurgenhaas]

What lasts long ... ;-)

I've now managed to build an initial Docker image which works pretty well. I only had to replace yarn with npm because I ran into issues when running mdshow setup as yarn doesn't install the bin directory of the node-jp module - but npm does.

Here is how you can use this:

docker pull registry.lakedrops.com/docker/mdshow
sudo curl -o /usr/local/bin/mdshow https://gitlab.lakedrops.com/docker/mdshow/-/raw/master/mdshow
sudo chmod +x /usr/local/bin/mdshow

mdshow

It runs as your current user, all created files are owned by yourself and auto-refresh does work as well.

You can see the source of this at https://gitlab.lakedrops.com/docker/mdshow

Give it a try and let me know what you think.

[jurgenhaas]

@jceb I have made some more improvements, so that it now really runs as the current user. Also added more packages that are required by Puppeteer for PDF creation, see https://github.com/puppeteer/puppeteer/blob/main/docs/troubleshooting.md#chrome-headless-doesnt-launch-on-unix

Also added support for a custom theme which is recognized when the env variable MDSHOW_THEME_PATH is set.

Some remaining issues:

• When there is a custom theme, the make file rsyncs the scss file into $(MDSHOW_CONFIG)/reveal.js/css/theme/source/ but it doesn't call gulp to compile the CSS into $(MDSHOW_CONFIG)/reveal.js/dist/theme/, I've added, but maybe not in the best possible way for a make file
• Using symbolc links in $(MDSHOW_CONFIG)/reveal.js/dist/theme/%: $(MDSHOW_CONFIG)/theme/%/assets doesn't work. The arguments are switched and the way it was coded, the links pointed from a file to a directory. I have switched the arguments, added the file extension and also used copy instead of symlink
• When closing the serve process, there is a bunch of errors like this:

make: *** [/usr/local/bin/mdshow:209: serve] Error 1
make: *** Deleting intermediate file '/opt/mdshow/theme/sky/assets'
make: unlink: /opt/mdshow/theme/sky/assets: Is a directory
make: *** Deleting intermediate file '/opt/mdshow/theme/white/assets'
make: unlink: /opt/mdshow/theme/white/assets: Is a directory

What should really be deleted is /opt/mdshow/theme/sky/assets/sky.css instead of /opt/mdshow/theme/sky/assets, but I can't find where this is called and hence can't fix it.

Last but not least, the PDF creation fails because localhost:3000 is not accessible inside the container under this address. I need to find out the IP of the host and then use that instead of localhost.

If all that is fixed, I'm happy to turn that into a PR so that it finally lives again in this repository. Do you want to help me getting this across the finish line?

[jceb]

Great work, thank you a lot! Looking forward to the PR.

[jurgenhaas]

@jceb it's now working completely. The PDF task failed before because of missing sandbox support for chrome inside the container and as that is no longer supported anyways, I've added a new argument to the task which turns that off deliberately. Inside a container there is no security issue with that anyways.

Submitted the PR #4 and I'm looking forward to what you're saying.

[jurgenhaas]

@jceb are you still interested in supporting this? If not, I'd be happy to fork the project and maintain that feature myself. I don't mind either way, I just want to progress dynamically as we see a lot of benefit in this.

[jceb]

I'm all for it. I'll merge it once we've worked through the things that I remarked in https://github.com/jceb/mdshow/pull/4/files

[jurgenhaas]

I'm not seeing any comments in the PR, can you please check again?

[jceb]

The comments are in the code

[jurgenhaas]

Sorry, I'm not seeing any

[jceb]

@jurgenhaas I'm sorry that the PR never worked out. In the meantime, I've started a new approach called slidesdown at https://github.com/jceb/slidesdown. The goal is to create a lightweight, ideally zero installation markdown presentation tool with a optional local dependency to support fast hot reloading of presentations. The local component isn't there yet but you might find it useful regardless.

[jurgenhaas]

Thanks @jceb for getting back to me on this after such a long period of time ;-)

We've since built our own solution based on your original one. Out main focus was on creating a docker image, which can easily be used by everyone in our team without having to setup anything - other than docker ofcourse.

It's public as well and can be used by everyone, you can find it at https://gitlab.lakedrops.com:docker/mdshow

[jurgenhaas]

And the results are often published as static HTML files on our website, e.g. at https://www.lakedrops.com/en/slides is an overview where you can click through to each of the slide documents.

[jceb]

Sweet, thanks for sharing! I'm glad it is useful to you. Did you improve the hot reloading implementation? That's what got me eventually. The new solution is based on vite and has great potential to be way faster than mdshow. Furthermore, I got rid of pandoc's own :::: formatting tricks and replaced them with the officially supported markdown comments (https://revealjs.com/markdown/). The result is a better readable / renderable markdown document.

Since you publish the presentations you could give slidesdown a spin for a non-publishing workflow. It provides a zero setup loader that you can point to your markdown files: https://slidesdown.e-jc.de/loader.html.
For example, check out this random README turned into presentation: https://slidesdown.e-jc.de/?slides=https%3A%2F%2Fgithub.com%2Fjceb%2Fvmux%2Fblob%2Fmaster%2FREADME.md#/vmux

[jurgenhaas]

Looks nice. For us, we stay with what we have for the time being, as we'Re super busy with stuff and tend to follow the idea "don't change it if it's not broken" ;-)

[jceb]

One more thing. Please make sure that you include the LICENSE file in your copy of the repository. For example the file default.revealjs is also covered by the Apache license.

[jurgenhaas]

Good point, thank you.

[jceb]

@jurgenhaas FYI, slidesdown now also has a docker image and a very simple but powerful start script. The main thing that's lacking is documentation on theming as well as a layout that includes a header and footer. Theming works basically like mdshow but you have to manually compile the theme and host it somewhere. I hope you'll like it and I'd be really happy to hear your feedback!

[jurgenhaas]

@jceb congrats, this looks really nice. I will probably borrow several bits and pieces but we won't switch, I guess, because we've customized our own solution so much including local dev environment and CI/CD for deployment as well as integration into Drupal (our website backend), that we can't justify to start over. But your solution is amazing, congratulations!

[jceb]

No worries, feel free to mix and match!