📘GitBook

About

Site: gitbook.com

Docs: docs.gitbook.com

Sample: manual.makerdao.com

Support: [e-mail]

Features

Editor

• What you see is what you get (WYSIWYG) editor for Markdown

• Light/dark mode

  • Personal account settings > How to access your personal account settings > Account settings > Preferences

  • Toggle: cmd + k > Type Switch to [dark/light] mode.

Collaboration

• Member management

Version control systems (VCS)

• GitBook platform versioning

  • Version control

• Git Sync

  • Two-way syncing updates

    • GitBook to GitLab/GitHub repository

    • GitLab/GitHub repository to GitBook

Publish

• Custom readable links by default

  • [space-name].gitbook.io/[page-name]

  • e.g. open-guides.gitbook.io/gitbook

• Custom domains

  • Set a custom domain

• Layouts

  • Right menu (Overflow button "⬇️" if hidden in the top-right of the menu) > Page Layout

    • Docs page: "A standard page, with table of contents and an outline."

    • Editorial post: "No table of contents, but visible page outline. Great for blogs!"

    • Landing page: "A full-width page, with no table of contents and no outline."

Page Layout

• Static light/dark mode

  • Menu bar (Top when in non-edit mode) > Customize > Theme mode

  • See Space Customization > General > Theme mode

Security

• Data is encrypted in transit and once in storage on Google Cloud.

• See Security FAQ > Is customer data encrypted?

Opportunities

Editor

Buggy (P0)

• Cursor can lag.

• Sometimes errors copy and pasting.

Slight delay to publish (P1)

• Slightly slower to publish than Notion and HackMD which show updates to the current version in view mode instantly.

Publish

Copy and paste text (P0)

• Issues highlighting, copying, and pasting the published text including lists and links

• Sample video 2023-02-14

• Cannot copy and paste lists.

• Copying and pasting text with links technically works, but appears to the user that it is not highlighting the full text.

• This makes it hard for the reader to interact with the content.

• Browsers

  • Chrome: Not as bad. Missing some body content

  • Firefox: Missing lists and links.

Second-level unordered lists not formatting correctly (P0)

• This first-level bullet is formatted correctly.

  • This second-level bullet is not formatted correctly.

• Sample video 2023-02-14

• This can be confusing to the reader and appear to be a typo.

H4 headers are not available (P0)

• Useful as a replacement for bold text to use a header link in order to deep-link into.

Table of contents (ToC) viewable in different screen sizes (P1)

• The ToC is only displayed when the window takes up the full screen.

• This make it hard for the reader to navigate longer or complex content.

• Not as dynamic as HackMD’s navigation button for narrow screen views.

Global navigation menu is not dynamic when the table of contents (ToC) are showing (P1)

• It's useful to have both a ToC and navigation menu.

  • ToC helps quickly navigate within the current page.

  • Navigation menu helps move between related topics.

• Sample video 2023-02-14

• The menu should be dynamic based on the screen size and be manually collapsible (Similar to HackMD's UX).

Mobile app for reading and editing (P1)

Publish view light/dark mode (P2)

• Based on system settings

• Manual toggle for the user

Version control systems (VCS)

Radical integration (P2)

• Site: radicle.xyz

Hosting

Deploy to Arweave and IPFS (P2)

Research

Security

• Multi-factor authentication (MFA) (P0)

  • Only through third-parties: Google and GitHub

  • Workaround: Use a secure email as login without setting a password. e.g. Skiff or Proton Mail

• Offline backups and self-hosting (P0)

  • All .md files and directories

  • Backup workaround: Commit to GitLab/GitHub > Download all files and directories.

  • Self-hosting backup: GitLab/GitHub automation for auto-push hosting to Arweave or IPFS

UX

• Remove and/or minimize the left navigation menu (P1)

  • Workaround: Potentially customize in .md file on GitHub and sync with GitBook.

• Remove "Powered by GitBook" with paid version (P1)

This is not technical advice. Always read the official documentation and do your own research.