dartbook

Description:

dartbook

Dartbook is a dart implementation of gitbook-cli for guys who loves gitbook.


Installation #

Requirement: Dart sdk >= 3.0

dartbook should be "activated".
$ dart pub global activate dartbook
$ export PATH=$PATH:~/.pub-cache/bin
copied to clipboard
Create a book #
set up a boilerplate book:
$ dartbook init
copied to clipboard
Preview and serve your book using:
$ dartbook serve
copied to clipboard
Build the static website using:
$ dartbook build
copied to clipboard
Show what have changed in one document:
$ dartbook diff [file1] [file2] ...
copied to clipboard
Nearly same with gitbook!
Feature #

Write using Markdown
Patch diff of characters
Output as a website or ebook (pdf, epub, mobi)
Multi-Languages
Lexicon / Glossary
Variables and Templating
Content References
Material default theme

Why #
Dartbook aims to smooth the migration from GitBook (Legacy) to Dart.
gitbook-cli stopped developping since 5 years ago, it was used widely but with many shortage.
First, it is very slow, especially for those books containing over 100 pages, in my case, it cost over 5 minutes for my project, which contains 3 language books, 168 pages for each.
Second, it contains some issues, e.g. glossary matching in different lingual text.
There is a nodejs project forked of gitbook called honkit, but it inherits bugs and errors since gitbook, and its update and bug-fixing is not so active.
What #
Try to keep everything same with gitbook, dartbook is compatible to run existing book projects. A little differences are:


No glossary generated page. All glossary entries are shown as tooltip, no more link jumping.


Encoding text as slug id. In different lingual text, many glossories contain special characters.


No mulilingual book any more in code, every book is managed by BookContext. langPath of Book is '' if book is located in project root.


Book navigation would ignore invalid link article.


No more font-sizing, theme-changing settings config, but they would come back in the future if new UX design appears.


Extension #
Using dartbook, it is easy to custom your book website, just create 'theme' in book project's root directory, and create '_layouts' for your book's pages' layout, '_i18n' for different i18n string resources and '_assets' for appearance. It keeps same with gitbook's style.
Theme development #
Dartbook's theme based on materialize css framework. If you would like to custom your own theme style, just did as follow steps:

Download latest materialize source package, e.g. materialize-src-v1.2.0.zip. Extract it and move its sass directory to $dartbookRoot/theme/web. We need materialize's components to build our own styles.
Install dart sass command line tool: dart pub global activate webdev sass, of course, make sure your envrionment variables include ~/.pub-cache/bin: export PATH=$PATH:~/.pub-cache/bin.
cd $dartbookRoot/theme && sass web/styles.scss web/styles.css, and then run webdev serve.
Open http://127.0.0.1:8080 in your browser, and start to modify something.
git clone https://github.com/lindeer/dartbook-theme-default and export its path as $assetRoot.
main.dart would finally compile to dartbook.js, its main functionality is to show glossary tooltips and bind events for them. materialize.js is entirely copied as dartbook's assets. build.sh is a helper script for file copy and rename, run it when you finally finished theme developing. The final material　produced by web (theme/build/*.css,*.js) would be applied into dartbook resources ($assetRoot/_assets).
In the directory $assetRoot, commit your changes and change the package name to dartbook_theme_xxx, what ever you like. Do not forget to change the theme name of ci files in your book project:

- - dart pub global activate dartbook_theme_default
+ - dart pub global activate dartbook_theme_xxx
copied to clipboard
Patch diff #
Git diff is based on line, that means whole line would be labeled even if one character is changed, it is extremely inconvenient to find what we haved revised when doing authoring work. Thanks to google-diff-match-patch, we could clearly take on the text change.
Just change command git diff [<options>] to dartbook diff [<options>], it would output precisely the revised character.

plugins system #
It is very powerful to use plugins to extend applications, but currently we had no plan for it.