Publishing a markdown CV with Github, Travis, Docker and Pandoc
About 6 months ago I started trying to work with simplified CV using Markdown.
Now I’ve got a CV which is source-controlled, and is published in multiple formats (HTML, PDF, Word) on commit.
I had to use this feature in anger today having spotted the word ‘technoolgy’ in a Word-rendered version.
What I haven’t done (yet) is have it /pushed/ to any potential readers.
When I started, I tried to use various markdown-to-PDF converters, none of which was satisfactory (e.g. markdown-pdf seemed ok, but actually just renders text into an image, wrapped as a PDF - CWjob won’t upload it once it goes > 1Mb).
Side note - I’m not dogmatic about the use of Markdown - it’s pretty much just sugar for a subset of HTML. Sadly the likes of Jekyll have made it a de facto standard because of the metadata/boilerplate. (I could hhappily rant on about XML/HTML and properly namespaced metadata which would reduce the need for tooling.)
This I discovered pandoc, and more importantly how to tame it with Docker.
The Process
(I’d use the lovely jekyll-ditaa plugin if github pages would allow it)
publishing flow
+------------------------------------------------------------------------------------------>
+--------------+ +--------------+ +---------------+ +--------+
| | | | | ++ | |
| local git | | remote git | | published || | github |
| CV | | CV | | formats || | pages |
| | | | | || | |
+--+-----+-----+ +------+--+----+ +--^-------------| +----^---+
| | ^ | +---------------+ |
| | | | | | |
| | committed by | | built by | | published by |
| | +---------------+ | | +-------------+ | | +--------------+ |
| | | | | | | | | | | | |
| +--^+ +-+ +----> travis/ +---+ +---> travis +--+
| | git | | docker | | |
| | | | pandoc | | |
| +---------------+ +-----+-------+ +------+-------+
| ^ ^
| | |
| locally built +----------------+ | +-------------+ |
+----------------> docker/ | | | travis | |
| pandoc | +-----+ config +-------+
+----------------+ | | |
| | | | |
| +----------------+ +-------------+
|
|
+--v------------+
| locally +-+
| published ||
| files ||
| ||
+----------------|
+---------------+
Testing and Committing changes
Having edited the CV, I may want to test changes before committing. This also tests the publishing process outside of travis: Testability is a big plus for docker.
There are several Docker images available - this one works for me…
https://github.com/vpetersson/docker-pandoc
I will type ‘make pdf’ (or ‘make all’) to test locally. This just triggers the publishing process within the pandoc container:
docker run -v $(pwd):/docs vpetersson/pandoc /bin/sh -c pandoc -V geometry:margin=1in -t latex -o out/cv.pdf cv.md
It was almost surprising how easily pandoc handles HTML and Word publishing out of the box. There is scope to add styling (via tex/css) to suit taste. I don’t feel the need to style my CV. The need to publish to Word format is entirely down to agencies/HR stuck in the stone age, unable to field PDFs. Yes. In 2015.
Publishing
There are numerious tutorials describing the use of Travis with Github pages. I found this Steve Klabnik post to be most enlightening, not least because it’s published by the same method.
The magic is in his “deploy.sh” script.
Basically, Github will automatically publish any project branch named ‘gh-pages’ at github.io. The publishing process builds a branch which contains only the generated files, and a CNAME file to handle requests from the www.bellesoft.uk domain. The files are now accessible from the root http://www.bellesoft.uk/ash-cv/
Subscribe
Subscribe to this blog via RSS.
Categories
Github 1
Travis 1
Docker 1
Pandoc 1
... 2
Recent Posts
-
Posted on 16 Dec 2015
-
Publishing a markdown CV with Github, Travis, Docker and Pandoc
Posted on 16 Sep 2015 -
Posted on 01 Sep 2015
Popular Tags
Github (1) Travis (1) Docker (1) Pandoc (1) ... (2) Enterprise (1) Dropwizard (1)