My project's data is version controlled by git, the documentation is written in markdown and is generated with pandoc using make.

I'm looking for a tool or a toolchain to automate and check the building of my documentation: Build, report errors, if none, deploy (i.e. copy documentation in PDF and HTML format to server).

I read up on CI tools, but they seem to be overkill for my needs and I'd very much welcome a lightweight solution.


If CI tools like Jenkins are overkill then you can carry on using make just add a target publish which does the following:

  1. Check that there are no uncommitted files git status and stop if there are
  2. git pull and update git pull
  3. build your target file(s) - if this fails, (i.e. returns a non-zero result), then make should stop
  4. Fingerprint the output file(s), e.g. SHA1, SHA256 even MD5 and compare to a record of the last fingerprint(s) - obviously this should fail, (return non-zero), if they match and thereby stop make.
  5. Perform the upload, returning non-zero on a problem
  6. Save the new fingerprint(s) on success
  7. You could even schedule this process to run on a periodic basis, (daily/hourly/weekly), or as the result of a push through post-push hooks.

Depending on your platform either it may be that all of the above items are available from the command line but you could implement all of the above using a very few short python scripts in a cross platform manner.

You might also consider replacing make with scons which is a python based build tool. Since it can use the MD5 of each file, including the output files, to determine what needs rebuilding it works really well with git and it can use the python requests library to publish results to a web server at the end of the build.


One possible solution for you may be https://www.gitbook.com/.

It is a service for git controlled books written in markdown. When the book has been published it can be downloaded as pdf/epub/mobi.

And for public books it's free!


If you need more, like a real CI software take a look at https://about.gitlab.com/gitlab-com/.

It's a free (git) repository hosting service (free for public and private repositories!) with a fully integrated CI-Server (former two products).


One of my favorite build tools is Kinook Visual Build. It is a commercial tool for ~300 USD. Support is done via forum with support staff looking into it and providing samples which really help you getting things right.

Unlike most CI tools which need an extra server, I use this one in standalone mode, i.e. I run it whenever I want. This is great for single developer projects where you needn't build often and needn't do it with each change in the repository.

I see the benefit of Visual Build in its graphical user interface and the possibility of debugging the build script.

Regarding your requirements:

and a lot more.

You didn't specify any OS. I run it on Windows 7 SP1 x64 but it is advertised for Vista through 10.

  • Thank you and sorry that I forgot to mention it: I'm looking for Linux software. – Jan Nov 16 '15 at 20:44

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.