use gitbook to generate ebook in 3 formats (pdf,epub,mobi)

[warren-bank]

Hi. This is something that I mostly whipped up for myself.. because I like keeping documentation offline, and I generally prefer PDF documents. The structure of your guide made it really easy. Hope you like :)

..a few quick comments:

• I was using Windows when I wrote the bash scripts
• a more robust implementation would need to modify:
  • ebook/.scripts/install.sh
  • to download and install a calibre binary that's correct for the platform
  • ebook/.scripts/env.sh
  • to adjust PATH and ensure that ebook-convert can be found within the installed version of calibre
  • .gitignore
  • to ensure that all flavors of this installed binary remain outside of the repo

[rupakg]

@warren-bank Thanks a lot for the PR. I love offline formats as well and glad you did it. I will review and get back to you. I appreciate it.

[rupakg]

@warren-bank Quick questions:

• Did you manually create the summary.md and book.readme.md or did the script generate it?
• If the script generates it, we don't need those files to be included in the repo. We just need the script, and instructions in the main README that shows how to use the script to generate the book.
• Also, I don't think the package*.json files should be committed.
• It would be interesting to see if you can take the link references in the markdown doc and convert them into footer comments like [1] www.xxxx.com/yyyy. This does not apply to the TOC though.
• It might be a good idea to add a Last Updated date/time stamp on the cover or somewhere else.
• Everything ebook related should be contained in that folder

Having said that, I feel I would have the script run as part of a CI build process on PR merges, which will use your script to generate a new eBook in all the three formats and dump them into the ebook folder.

I would appreciate your feedback.

[warren-bank]

Hi.

• In my initial version, I created these 2 files (SUMMARY.md and book.README.md) by hand. This methodology was used by the first 2 commits.
• In the 3rd commit, I added an additional script that parses README.md to generate 2 files (book_SUMMARY.md and book_README.md).
  • They are added to .gitignore.. so they are not included in the git repo.
  • They are also added to .bookignore.. so they ARE included by gitbook while it's running.
  • the parser script makes some pretty strong assumptions about the structure of README.md
  • a summary of links exists under the markdown header: "Table of Contents"
  • this summary extends until the next markdown header (ie: \n#)
• package.json is required, because it contains necessary (dev) dependencies
• package-lock.json is a new file that npm generates to lock all of the dependencies to an exact version number.
  • all subsequent calls to npm install will result in an identical environment
  • previously (ie: without this file), it was a bit of a free-for-all
  • the popular consensus is that this file should always be added to version control
• a gitbook plugin would be able to inspect per-page markdown content to identify all links
  • I'm not sure if there's an API to create per-page footnotes in the generated ebook document
  • I'm also not sure how markdown footnotes would be handled
  • this section of documentation is missing
  • if this is a thing.. I'd bet that there's already a plugin to do it
  • examples:
    • printlinks
• likewise, a gitbook plugin could be used to inject some additional markdown before the ebooks are generated
  • for example:
  • if page is 'book_README.md'
    • create and prepend a custom "cover" page
    • a better logo image
    • a nicely formatted timestamp
    • whatever additional info you may want..

[rupakg]

Hi @warren-bank Thanks for the detailed explanation. I want to keep the root folders clean of any ebook related files. Can you please move everything under the ebook folder - package*.json, SUMMARY.md, book.README.md, book.json, .bookignore, cover.jpg? The outputs of the ebook formats are nicely placed in the ebook folder, and the scripts etc. are under .scripts. That's all ok.

Hope that makes sense. Thx again for your work.

[warren-bank]

while such a clean division is not entirely possible..

I'm thinking:

• if package.json and book.json were moved to a subdirectory
  • book.json can configure the base directory.. point it back to root
  • the temporary markdown files would still need to be saved to the root directory, since they contain relative links that would break otherwise
  • cover.jpg would still need to be in the root directory

Is it really worth rejiggering things.. just to relocate a few small json configuration files?

PS) reminder: SUMMARY.md and book.README.md were deleted several commits ago

[warren-bank]

hmm.. this is hacky, but..

• what if the parser saved its output (ie: the 2 temporary markdown files) to: ebook/src/*.md
• it uses a regex to rewrite all of the relative links to: [../../source/]

this way:

• the book's root directory could be changed to: ebook/src
  • meaning that book.json and cover.json could also be relocated

[warren-bank]

I'll give it a quick test, and see what happens..

[warren-bank]

it may be hacky.. but it works perfectly :)

well.. almost:

• for some reason, the default layout template used internally by gitbook is no-longer finding its css files when generating the pdf document
  • I think this only happens on pages of markdown that occur outside of the book's src directory (ie: ../../source/*.md)
  • there's probably a clever way to fix it, but off-hand.. I have no idea how

[rupakg]

@warren-bank Thx for the updates. I like it. It is so clean now. As far as the CSS is concerned, there might be a config option to gitbook that solves it. But, awesome work. Very close to getting merged. Let's get the CSS resolved.

[warren-bank]

agreed.. I'm pretty deep in the weeds with the css issue right now.. and it's really weird; it's definitely an issue with gitbook. Once I get it figured out.. I'll probably have a PR for the gitbook repo too :-/

[rupakg]

@warren-bank Thx for working on the feedback I provided. I appreciate it. I will review the work and let you know.