Links

Why GitBook?

Requirements:
  • Easy maintenance
  • Git/file system support
    • In theory, easy migration to different platforms
    • Doesn't require me to have internet access
    • I can easily do a grep or ack locally to find information.
    • Markdown support
    • Easy styling
Pros:
  • Nice UI
  • Decent free Basic plan
    • Includes one free private book
  • No need to always use command line
  • Custom domains
  • Google Analytics support
    • Bi-directional support
    • I can make hooks into GitBook via GitHub hooks, see gitbook-summary
  • Renaming pages appears to maintain old URLs
    • Only if it is not moved to a different folder
  • Works decently on my 11” iPad Pro 2018
    • Browsing is fine on quarter, half or full screen
    • Can’t use Safari’s split screen mode for editing
      • Require’s using full screen, sad
  • Works 1146px width (UWQD Display: 3440 / 3)
Cons:
  • Organizing a lot of pages is difficult, even if nested
    • At 59 pages, it was already difficult to reorganize
    • I may have to organize things on the filesystem/markdown
    • I could potentially move to a second GitBook, but I like everything organized in one for now
  • Long pages can be very confusing
    • Better to break out the content into different pages
    • Increases the problem of organizing a lot of pages
  • Content is not really "static"
Dislikes:
  • Doesn't use same header shortcuts as Google Docs
Limitations:
  • Single theme
    • I don't really mind it. It's a decent but most importantly, usable theme.
  • Logs to git commit history could be nicer
  • No offline read/write support
    • Workaround is to download the repository
  • Moving pages doesn't redirect to new URL
    • For renaming pages in the same directory structure, the old url still works
    • For moving pages into a different directory, the old url will not work
  • I tried to compile a version using their gitbook-cli tool but it failed on notes/javascript/fetch.md
Facts:
  • GitBook stores assets/images under .gitbook/assets
  • Assets retain their filename
Other static site generators: https://www.staticgen.com
Previously using Phenomic. cons: Fully manual.
Other notable GitBooks:
Other

Available Content Features

B​esides the standard Markdown features.

Task List

  • Incomplete Task
  • Completed Task

Hints

Info
Warning
Danger
Success

Tabs

First Tab
Second Tab
Tabs

Alternatives

Notion

Tree structure doesn't work so well for content which can exist in multiple branches.
I put everything in a single table and use tags.
Pros:
  • WYSIWYG
Cons:
  • Exporting isn't easy
  • No history
  • No automatic export