Skip to content

WIP: Publish handbook as epub

Toon Claes requested to merge (removed):tc-handbook-epub into master

This is actually a follow-up to @nick.thomas's MR !2940 (closed).

This adds a rake task to build a single epub file of the GitLab Handbook. This can be installed on any e-reader.

How it works:

  1. All .md of the handbook are joined in one big all-in-one markdown file.
  2. During the process links are adjusted so conflicts between anchors do not occur.
  3. The all-in-one markdown is converted by middleman
  4. The single html page created by middleman is converted to epub by pandoc.

It might feel like a very cumbersome method, but this is the best method I could find.

@nick.thomas mentioned some tasks in his MR:

  • Missing images like https://github.com/jgm/pandoc/issues/1450
  • Pandoc doesn't support all markdown extensions we use
  • Needs a funky cover image
  • Many internal links don't work. (EDIT: This might need some double checking)
  • Many warnings like this in the generated output

But there also some other things that need to figured out:

  • Make it work side-to-side with the regular handbook webpage. (at the moment that one is deleted)
  • Code is really dirty and hard to maintain, fix that. I am really open on suggestions on how to improve that.
  • Title and some other attributes are not set yet.
  • Undo the hack for the team/structure proxy.
  • Add it to CI and make it downloadable.
  • optional: Also build a pdf.

At the moment this is the epub that rolls out: handbook.epub

I don't think it is good, but it should be complete and be actual usable.

Related issues

#689

Merge request reports