@dicortazar I would be really curious to hear your opinion about the challenges and proposal above, as you have all the working knowledge from producing the gitbook so far.

Some other relevant links if we want to use pandoc for this:

• Writing a Book with Pandoc, Make, and Vim (and hackernews discussion)
• Using Pandoc to publish a book in multiple file formats: experiences and wishes
• Customizing pandoc to generate beautiful pdfs from markdown

Thanks for the write-up @spier!
I did a bit of searching here too and found this nice LaTeX template to be used with PanDoc:

• https://github.com/Wandmalfarbe/pandoc-latex-template
• Pandoc themselves keep this list of contributed templates: https://github.com/jgm/pandoc/wiki/User-contributed-templates
• General Pandoc demo: https://pandoc.org/demos.html

Here's something more, German language though

• https://vijual.de/2019/03/11/artikel-mit-markdown-und-pandoc-schreiben/
• https://baireuther.de/page/pandoc/

And matching Docker images (or their source repos) we can hopefully build upon:

• https://github.com/pandoc/dockerfiles#available-images
• https://gitlab.com/raabf/dockertex/

One commercial service rendering books from markup:
https://bookdown.org/

So many options :) Great to know that pandoc can also do epub.

I will try to find something that can use a GitHub Action to build both a PDF and an epub. Let's see :)

So many options :) Great to know that pandoc can also do epub.

I will try to find something that can use a GitHub Action to build both a PDF and an epub. Let's see :)

If there isn't any GitHub action will actually happily run any Docker container or even blank shell scripts.
So if there isn't anything readymade in the marketplace or directly usable from within the Pandoc Docker repos we can just hack our own...

Another example of a gitbook produced from a github repo:

• repo: https://github.com/OWASP/owasp-masvs
• book: https://mobile-security.gitbook.io/masvs/

Btw I am starting to look into gitbooks today. If there is any gitbooks expert that sees this here and wants to help, let me know :)

Btw I am starting to look into gitbooks today. If there is any gitbooks expert that sees this here and wants to help, let me know :)

Sounds great, @dicortazar already has a bit of GitBook experience.
We also have a non-profit commercial subscription for it, that will likely come in handy.

Looking forward to see a WIP PR for it so others can join in. Could you try to push that to a different branch than master for now so we can possibly merge more material while iterating on the rendering?

Found this GitHub Action that might be useful for it: https://github.com/marketplace/actions/gitbook-action

I also took a look at the OWASP example, that's a great find! 👍

• They render fully automatic using GitHub Actions
• Their fixed artifact (PDF / EPUB / ...) rendering is based on Pandoc, ConTeXt and the Eisvogel template all done & integrated. That's something awesome we hopefully can recycle.

Yep, I am already working on a branch book (have not created a PR yet).

For now I am shooting for a gitbook only (that will also provide a PDF download).

It looks like I can create that directly with the GitHub integration available in gitbook, but maybe that GitHub Actions offers more flexibility. We can check that.

I will share what I have once I have learned a bit more about it. Latest next week.

In an effort to release early and often, here a first experiment:
https://innersourcecommons.gitbook.io/innersource-patterns-staging/v/book/

It is based of this branch:
https://github.com/spier/InnerSourcePatterns/tree/book

I will send a PR later and summarize what I have tried, and how this book works right now.

Looks good to me. I think I'll give the Pandoc magic of OWASP a go once I find a bit of time. I should give us a bit more flexibility when it comes to nice, book-style rendering.
Not sure what Gitbook offers us in that regard.

Looking forward to the PR. Feel free to also just open up a WIP-PR if you like.

Indeed it looks like gitbook offers very few layouting options. Since they moved their service away from their CLI approach and exclusively to a SaaS offering on gitbook.com they have greatly reduce the amount of configuration options for their service.

I am still a bit unsure if the pandoc approach will be sustainable for us, assuming that it will be more complex to setup and maintain (and we have very few maintainers right now :)).

One option could be to do run with the gitbook approach for a little while, which helps us to create the missing guidelines for level 2 and 3. If we then realize that the content is good but the format isn't pretty enough, we could still look at the pandoc approach in addition to gitbook (or maybe even as a replacement).

Will push a WIP PR now.

Indeed it looks like gitbook offers very few layouting options. Since they moved their service away from their CLI approach and exclusively to a SaaS offering on gitbook.com they have greatly reduce the amount of configuration options for their service.

Great thanks for the insight! Can you point to some point of their docs detailing the options/restrictions around PDF layout they provide?

I am still a bit unsure if the pandoc approach will be sustainable for us, assuming that it will be more complex to setup and maintain (and we have very few maintainers right now :)).

It's not more complex than what we already use to render the learning path, effectively supported by a large OSS organization and highly popular, proven software.
And who knows it might even attract more people that are interested in this - especially given that this will enable us to render both Patterns and LP content to pretty PDF and EPUB files.

One option could be to do run with the gitbook approach for a little while, which helps us to create the missing guidelines for level 2 and 3. If we then realize that the content is good but the format isn't pretty enough, we could still look at the pandoc approach in addition to gitbook (or maybe even as a replacement).

Both approaches are entirely independent. Gitbook is fine for pretty online rendering and apparently some PDF rendering until we have something better.

If this double approach works for OWASP, it works for us, especially since we can pretty much copy their approach.

Will push a WIP PR now.

Great, thanks.

Indeed it looks like gitbook offers very few layouting options. Since they moved their service away from their CLI approach and exclusively to a SaaS offering on gitbook.com they have greatly reduce the amount of configuration options for their service.

Great thanks for the insight! Can you point to some point of their docs detailing the options/restrictions around PDF layout they provide?

So the formatting options for text and images can be found here:
https://docs.gitbook.com/editing-content/rich-content

It's pretty basic stuff that is mostly also available when formatting content in markdown.

I have not seen any specific formatting options for the PDF output actually. gitbook just offers an "Export as PDF" option and that seems to be it.