Howto serve a markdown document
Allmark is a simple self contained Markdown html renderer and server from developer Andreas Koch, that is written in Go.
You could certainly install Allmark locally, but there are numerous editors or standalone operating system specific markdown parsers you could use.
But what if you have some markdown documentation on a server, and need a quick and easy way to access that documentation? You can always just look at the raw markdown using vim, but what fun is that?
Allmark is a full markdown server, but installing a server just to read a couple of markdown documents is something very few people would want to do. If however, your server has docker installed, you can be reading your documentation in all its rendered glory in a matter of a few seconds. Here is how:
You could certainly install Allmark locally, but there are numerous editors or standalone operating system specific markdown parsers you could use.
But what if you have some markdown documentation on a server, and need a quick and easy way to access that documentation? You can always just look at the raw markdown using vim, but what fun is that?
Allmark is a full markdown server, but installing a server just to read a couple of markdown documents is something very few people would want to do. If however, your server has docker installed, you can be reading your documentation in all its rendered glory in a matter of a few seconds. Here is how:
This is an example of where Docker is an incredible tool for the job. Of course your server needs to have Docker installed for this to work, but if you do, then your document is one docker run command away!
Thanks to the Allmark author Andreas Koch, there's a Docker image available on Docker Hub.
Like many such docker images, there isn't any documentation provided, but have no fear, I've done the work of deciphering the docker file for you.
The specifics:
In most cases that will be the easiest and fastest way to accomplish this. Just cd to the directory with your .md files and startup your allmark docker container there.
Howto serve your markdown documentation using the allmark docker image
I promised simplicity -- so here you have it:
cd /somedir/withmarkdownFile
docker run -dit --name allmark -v $(pwd):/data -p 8888:33001 andreaskoch/allmark
Once the container is running, open a browser and access the url http://yourdomain:8888
Just make sure that you don't have a firewall on the server blocking access to whatever port you've chosen.
If you're done reading the markdown documentation, simply docker remove (docker rm) your allmark container using -f to force the removal. This will cleanup the container files leaving only the image.
docker rm -f allmark
Quick note on images & attachments
It is an Allmark requirement that images and attachments referenced in the markdown document be in a subdirectory name /files. If an embedded image doesn't work, you might need to make a /files dir and copy it in there.
Thanks to the Allmark author Andreas Koch, there's a Docker image available on Docker Hub.
Like many such docker images, there isn't any documentation provided, but have no fear, I've done the work of deciphering the docker file for you.
The specifics:
- The allmark server listens on ports 33001-33002. So you will need to either access that port directly with your web browser, or map it to a local port. In this example, I'm mapping port 8888 to it.
- When the server starts it sets the document path to '/data', so you need to set your docker volume using -v to either a specific directory on your server, or the 'present working directory' which is the option I chose here.
In most cases that will be the easiest and fastest way to accomplish this. Just cd to the directory with your .md files and startup your allmark docker container there.
Howto serve your markdown documentation using the allmark docker image
I promised simplicity -- so here you have it:
cd /somedir/withmarkdownFile
docker run -dit --name allmark -v $(pwd):/data -p 8888:33001 andreaskoch/allmark
Once the container is running, open a browser and access the url http://yourdomain:8888
Just make sure that you don't have a firewall on the server blocking access to whatever port you've chosen.
If you're done reading the markdown documentation, simply docker remove (docker rm) your allmark container using -f to force the removal. This will cleanup the container files leaving only the image.
docker rm -f allmark
Quick note on images & attachments
It is an Allmark requirement that images and attachments referenced in the markdown document be in a subdirectory name /files. If an embedded image doesn't work, you might need to make a /files dir and copy it in there.
Trackbacks
No Trackbacks
Comments
Display comments as Linear | Threaded