The source project of this merge request has been removed.
WIP: Publish handbook as epub
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:
- All
.md
of the handbook are joined in one big all-in-one markdown file. - During the process links are adjusted so conflicts between anchors do not occur.
- The all-in-one markdown is converted by
middleman
- The single html page created by
middleman
is converted toepub
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.