2016-02-18 04:36:33 +01:00
|
|
|
Crowbook
|
|
|
|
========
|
|
|
|
|
2016-02-25 19:12:45 +01:00
|
|
|
[![Build Status](https://travis-ci.org/lise-henry/crowbook.svg?branch=master)](https://travis-ci.org/lise-henry/crowbook)
|
|
|
|
|
2016-08-18 01:33:56 +02:00
|
|
|
Render a book written in markdown to HTML, Epub or PDF.
|
2016-02-18 04:36:33 +01:00
|
|
|
|
2016-02-21 21:16:01 +01:00
|
|
|
Crowbook's purpose is to allow you to automatically generate multiple
|
|
|
|
outputs formats from a book written in Markdown. Its main focus is
|
2016-03-01 21:41:23 +01:00
|
|
|
novels, and the default settings should (hopefully) generate readable
|
|
|
|
books with correct typography.
|
2016-02-21 21:16:01 +01:00
|
|
|
|
2016-03-01 21:41:23 +01:00
|
|
|
Example
|
|
|
|
-------
|
|
|
|
|
|
|
|
To see what Crowbook's output looks like, you can read (a
|
|
|
|
not-necessarily up-to-date version of) the Crowbook
|
|
|
|
guide (containing this README.md file and additional documentation)
|
|
|
|
rendered in [HTML](http://lise-henry.github.io/crowbook/book.html),
|
|
|
|
[PDF](http://lise-henry.github.io/crowbook/book.pdf) or [EPUB](http://lise-henry.github.io/crowbook/book.epub).
|
2016-02-25 19:12:45 +01:00
|
|
|
|
2016-02-18 04:36:33 +01:00
|
|
|
|
2016-02-25 16:20:33 +01:00
|
|
|
Installing
|
|
|
|
----------
|
|
|
|
|
2016-03-01 21:41:23 +01:00
|
|
|
### Packages ###
|
|
|
|
|
|
|
|
If you are on Debian GNU/Linux or Ubuntu (on a PC architecture), you can
|
|
|
|
download `.deb` packages on
|
|
|
|
[the releases page](https://github.com/lise-henry/crowbook/releases).
|
2016-02-25 16:20:33 +01:00
|
|
|
|
|
|
|
### Binaries ###
|
2016-02-21 18:28:48 +01:00
|
|
|
|
2016-02-26 19:23:06 +01:00
|
|
|
See [the releases page](https://github.com/lise-henry/crowbook/releases)
|
2016-02-25 16:20:33 +01:00
|
|
|
to download a precompiled binary for your architecture (currently:
|
|
|
|
Linux, Windows and MacOSX). Just extract the archive and run
|
2016-03-01 18:46:59 +01:00
|
|
|
`crowbook` (or `crowbook.exe` on Windows). You might also want to copy
|
|
|
|
the binary somewhere in your `PATH` for later usage.
|
2016-02-25 16:20:33 +01:00
|
|
|
|
|
|
|
### Building ###
|
|
|
|
|
|
|
|
You'll need to have the [Rust](https://www.rust-lang.org/) compiler
|
2016-02-21 18:28:48 +01:00
|
|
|
on your machine first; you can
|
|
|
|
[download and install it here](https://www.rust-lang.org/downloads.html). Once
|
|
|
|
it is down:
|
|
|
|
|
2016-09-15 22:05:11 +02:00
|
|
|
```bash
|
2016-02-21 18:28:48 +01:00
|
|
|
$ cargo install crowbook
|
|
|
|
```
|
|
|
|
|
2016-02-25 16:20:33 +01:00
|
|
|
will automatically download the latest `crowbook` release on
|
2016-02-26 19:23:06 +01:00
|
|
|
[crates.io](https://crates.io/crates/crowbook) and install it.
|
2016-02-21 18:28:48 +01:00
|
|
|
|
2016-02-19 23:01:34 +01:00
|
|
|
Usage
|
|
|
|
-----
|
|
|
|
|
2016-02-20 17:13:14 +01:00
|
|
|
The simplest command is:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
$ crowbook <BOOK>
|
|
|
|
```
|
|
|
|
|
2016-03-01 21:41:23 +01:00
|
|
|
where `BOOK` is a configuration file. Crowbook will parse this
|
2016-02-25 16:20:33 +01:00
|
|
|
file and generate a book in HTML, Epub, LaTeX, and/or PDF,
|
2016-03-22 17:47:42 +01:00
|
|
|
according to the settings in the configuration file.
|
2016-02-21 20:33:30 +01:00
|
|
|
|
2016-02-25 16:20:33 +01:00
|
|
|
To create a new book, assuming you have a
|
2016-02-21 20:33:30 +01:00
|
|
|
list of Markdown files, you can generate a template configuration file
|
|
|
|
with the `--create` argument:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
$ crowbook --create my.book chapter_*.md
|
|
|
|
```
|
|
|
|
|
2016-03-01 21:41:23 +01:00
|
|
|
This will generate a default `my.book` file, which you'll need to
|
|
|
|
complete. This configuration file contains some metadata, options, and lists the
|
2016-03-22 17:47:42 +01:00
|
|
|
Markdown files.
|
2016-02-19 23:01:34 +01:00
|
|
|
|
2016-02-20 17:13:14 +01:00
|
|
|
For more information see
|
2016-03-01 21:41:23 +01:00
|
|
|
[the configuration file](book_example/config.md).
|
2016-02-20 17:13:14 +01:00
|
|
|
|
2016-02-21 05:29:40 +01:00
|
|
|
It is also possible to give additional parameters to `crowbook`;
|
2016-02-21 20:33:30 +01:00
|
|
|
we have already seen `--create`, but if you want the full list, see
|
2016-03-01 21:41:23 +01:00
|
|
|
[the arguments](book_example/arguments.md).
|
2016-02-19 23:01:34 +01:00
|
|
|
|
2016-02-21 21:16:01 +01:00
|
|
|
Current features
|
|
|
|
----------------
|
|
|
|
|
|
|
|
### Output formats ###
|
|
|
|
|
2016-03-22 17:47:42 +01:00
|
|
|
Crowbook should correctly support HTML and EPUB (either
|
2016-02-21 21:16:01 +01:00
|
|
|
version 2 or 3) as output formats: rendered files should pass
|
|
|
|
respectively the [W3C validator](https://validator.w3.org/) and the
|
|
|
|
[IDPF EPUB validator](http://validator.idpf.org/) for a wide range of
|
|
|
|
(correctly Markdown formatted) input files. See the example book
|
|
|
|
rendered in [HTML](http://lise-henry.github.io/crowbook/book.html) and
|
|
|
|
[EPUB](http://lise-henry.github.io/crowbook/book.epub) on github.io.
|
|
|
|
|
2016-03-22 17:47:42 +01:00
|
|
|
LaTeX/PDF output is a bit more tricky: it should work reasonably well for
|
2016-02-25 16:20:33 +01:00
|
|
|
novels (the primary target of Crowbook), but `pdflatex` might occasionally
|
2016-03-22 17:47:42 +01:00
|
|
|
choke on some "weird" unicode character. See the example book rendered
|
|
|
|
in [PDF](http://lise-henry.github.io/crowbook/book.pdf) on github.io.
|
2016-02-21 21:16:01 +01:00
|
|
|
|
2016-09-09 22:35:36 +02:00
|
|
|
ODT output is currently experimental at best. It might work with very
|
|
|
|
basic formatting but still needs a *lot* of work. You can still see
|
|
|
|
the example book rendered in
|
|
|
|
[ODT](http://lise-henry.github.io/crowbook/book.odt) on github.io to
|
|
|
|
have an idea of the current status for this output format.
|
2016-02-21 21:16:01 +01:00
|
|
|
|
|
|
|
### Input format ###
|
|
|
|
|
|
|
|
Crowbook uses
|
|
|
|
[pulldown-cmark](https://crates.io/crates/pulldown-cmark) and thus
|
2016-03-01 18:46:59 +01:00
|
|
|
should support most of CommonMark Markdown. Inline HTML, however, is
|
2016-02-23 23:51:21 +01:00
|
|
|
not implemented, and probably won't be, as the goal is to have books
|
2016-02-25 16:20:33 +01:00
|
|
|
that can also be generated in PDF (and maybe eventually ODT).
|
2016-02-21 21:16:01 +01:00
|
|
|
|
|
|
|
Maybe the most specific "feature" of Crowbook is that (by default, it
|
2016-02-25 16:20:33 +01:00
|
|
|
can be deactivated) it tries to "clean" the input files. By default this
|
2016-02-21 21:16:01 +01:00
|
|
|
doesn't do much (except removing superfluous spaces), but if the
|
|
|
|
book's language is set to french it tries to respect french
|
|
|
|
typography, replacing spaces with non-breaking ones when it is
|
|
|
|
appropriate (e.g. in french you are supposed to put a non-breaking
|
|
|
|
space before '?', '!', ';' or ':'). This feature is relatively limited
|
|
|
|
at the moment, but I might try to add more options and support for
|
|
|
|
more languages.
|
|
|
|
|
2016-02-27 04:40:23 +01:00
|
|
|
### Links handling ###
|
|
|
|
|
|
|
|
Crowbook tries to correctly translate local links in the input
|
|
|
|
Markdown files: e.g. if you have a link to a markdown file that is
|
|
|
|
part of your book, it will be transformed into a link inside the
|
|
|
|
document.
|
|
|
|
|
2016-03-01 21:41:23 +01:00
|
|
|
### Inline YAML blocks ###
|
|
|
|
|
2016-03-22 17:47:42 +01:00
|
|
|
Crowbook supports inline YAML blocks:
|
2016-03-01 21:41:23 +01:00
|
|
|
|
2016-09-15 22:05:11 +02:00
|
|
|
```yaml
|
2016-03-01 21:41:23 +01:00
|
|
|
---
|
|
|
|
author: Me
|
|
|
|
title: My title
|
|
|
|
---
|
|
|
|
```
|
|
|
|
|
2016-03-22 17:47:42 +01:00
|
|
|
This is mostly useful when Crowbook is runned with the `--single`
|
2016-09-09 22:51:47 +02:00
|
|
|
argument (receiving a single Markdown file instead of a book
|
|
|
|
configuration file). E.g., the following Markdown file:
|
|
|
|
|
2016-09-15 22:05:11 +02:00
|
|
|
```yaml
|
2016-09-09 22:51:47 +02:00
|
|
|
---
|
|
|
|
author: John Doe
|
|
|
|
title: A book
|
|
|
|
|
|
|
|
output.html: book.html
|
|
|
|
---
|
|
|
|
|
|
|
|
This is a very tiny book!
|
2016-09-10 00:19:57 +02:00
|
|
|
```
|
2016-09-09 22:51:47 +02:00
|
|
|
|
|
|
|
can be processed with `crowbook --single foo.md` or `crowbook -s
|
|
|
|
foo.md` to produce the `book.html` file. This is useful for short
|
|
|
|
texts that typically only contain one "chapter".
|
2016-03-01 21:41:23 +01:00
|
|
|
|
|
|
|
### Bugs ###
|
2016-02-19 23:01:34 +01:00
|
|
|
|
2016-03-03 18:26:07 +01:00
|
|
|
See the [github's issue tracker](https://github.com/lise-henry/crowbook/issues).
|
2016-02-19 23:01:34 +01:00
|
|
|
|
2016-03-22 17:38:54 +01:00
|
|
|
Contributors
|
|
|
|
------------
|
|
|
|
|
2016-03-22 17:40:50 +01:00
|
|
|
* [Stéphane Mourey](http://stephanemourey.fr/) `<s+crowbook AT stephanemourey DOT fr>`
|
2016-03-22 17:38:54 +01:00
|
|
|
|
2016-02-19 23:01:34 +01:00
|
|
|
Acknowledgements
|
|
|
|
----------------
|
|
|
|
|
2016-09-16 21:47:15 +02:00
|
|
|
Besides the [Rust](https://www.rust-lang.org/) compiler and standard
|
|
|
|
library, Crowbook uses the following libraries:
|
2016-02-19 23:01:34 +01:00
|
|
|
|
2016-03-22 17:38:54 +01:00
|
|
|
* [pulldown-cmark](https://crates.io/crates/pulldown-cmark)
|
|
|
|
* [yaml-rust](https://crates.io/crates/yaml-rust)
|
|
|
|
* [mustache](https://crates.io/crates/mustache)
|
|
|
|
* [clap](https://github.com/kbknapp/clap-rs)
|
|
|
|
* [chrono](https://crates.io/crates/chrono)
|
|
|
|
* [uuid](https://crates.io/crates/uuid)
|
2016-09-13 02:45:27 +02:00
|
|
|
* [mime_guess](https://crates.io/crates/mime_guess)
|
|
|
|
* [crossbeam](https://crates.io/crates/crossbeam)
|
2016-03-22 17:38:54 +01:00
|
|
|
* [walkdir](https://crates.io/crates/walkdir)
|
2016-03-22 17:47:42 +01:00
|
|
|
* [rustc-serialize](https://crates.io/crates/rustc-serialize)
|
2016-02-19 23:01:34 +01:00
|
|
|
|
2016-09-16 21:47:15 +02:00
|
|
|
It also embeds [Highlight.js](https://highlightjs.org/) in HTML output
|
|
|
|
to enable syntax highlighting for code blocks.
|
|
|
|
|
2016-02-23 23:51:21 +01:00
|
|
|
It also uses configuration files from
|
2016-02-26 23:16:47 +01:00
|
|
|
[rust-everywhere](https://github.com/japaric/rust-everywhere) to use
|
2016-03-01 21:41:23 +01:00
|
|
|
[Travis](https://travis-ci.org/) and
|
2016-02-26 23:16:47 +01:00
|
|
|
[Appveyor](http://www.appveyor.com/) to generate binaries for
|
2016-02-23 23:51:21 +01:00
|
|
|
various platforms on each release.
|
|
|
|
|
2016-02-27 17:02:35 +01:00
|
|
|
While Crowbook directly doesn't use them, there was also inspiration
|
|
|
|
from [Pandoc](http://pandoc.org/) and
|
|
|
|
[mdBook](https://github.com/azerupi/mdBook).
|
|
|
|
|
|
|
|
Also, the [W3C HTML validator](https://validator.w3.org/) and the
|
|
|
|
[IDPF EPUB validator](http://validator.idpf.org/) proved very useful
|
|
|
|
during development.
|
2016-02-19 23:01:34 +01:00
|
|
|
|
2016-02-21 18:28:48 +01:00
|
|
|
ChangeLog
|
|
|
|
---------
|
|
|
|
|
|
|
|
See [ChangeLog](ChangeLog.md).
|
|
|
|
|
|
|
|
Library
|
|
|
|
-------
|
|
|
|
|
|
|
|
While the main purpose of Crowbook is to be runned as a command line,
|
2016-02-25 16:20:33 +01:00
|
|
|
the code is written as a library, so if you want to build on it you can
|
2016-09-09 23:10:44 +02:00
|
|
|
use it as such. You can look at the generated documentation on
|
|
|
|
[docs.rs](https://docs.rs/releases/search?query=crowbook).
|
2016-02-21 18:28:48 +01:00
|
|
|
|
|
|
|
License
|
|
|
|
-------
|
2016-02-19 23:01:34 +01:00
|
|
|
|
2016-09-16 21:47:15 +02:00
|
|
|
|
|
|
|
|
2016-02-21 18:28:48 +01:00
|
|
|
Crowbook is free software: you can redistribute it and/or modify it
|
|
|
|
under the terms of the GNU Lesser General Public License (LGPL),
|
|
|
|
version 2.1 or (at your option) any ulterior version. See
|
2016-03-01 21:41:23 +01:00
|
|
|
[LICENSE](LICENSE.md) for more information.
|
2016-02-23 23:51:21 +01:00
|
|
|
|
2016-09-16 21:47:15 +02:00
|
|
|
Crowbook's logo is licensed under the [Creative Commons Attribution 4.0
|
|
|
|
International license](https://creativecommons.org/licenses/by/4.0/deed.en),
|
|
|
|
based on the
|
|
|
|
[Rust logo](https://commons.wikimedia.org/wiki/File:Rust_programming_language_black_logo.svg)
|
|
|
|
by Mozilla Corporation.
|
|
|
|
|
|
|
|
Crowbook includes binary (minified) CSS and Javascript files from
|
|
|
|
[Highlight.js](https://highlightjs.org/), written by Ivan
|
|
|
|
Sagalaev, licensed under the following terms:
|
2016-02-23 23:51:21 +01:00
|
|
|
|
2016-09-16 21:47:15 +02:00
|
|
|
> Copyright (c) 2006, Ivan Sagalaev
|
|
|
|
>
|
|
|
|
> All rights reserved.
|
|
|
|
>
|
|
|
|
> Redistribution and use in source and binary forms, with or without
|
|
|
|
> modification, are permitted provided that the following conditions are met:
|
|
|
|
> * Redistributions of source code must retain the above copyright
|
|
|
|
> notice, this list of conditions and the following disclaimer.
|
|
|
|
> * Redistributions in binary form must reproduce the above copyright
|
|
|
|
> notice, this list of conditions and the following disclaimer in the
|
|
|
|
> documentation and/or other materials provided with the
|
|
|
|
> distribution.
|
|
|
|
> * Neither the name of highlight.js nor the names of its contributors
|
|
|
|
> may be used to endorse or promote products derived from this software
|
|
|
|
> without specific prior written permission.
|
|
|
|
>
|
|
|
|
> THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
|
|
|
|
> EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
|
|
> WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
|
|
> DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
|
|
|
|
> DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
|
|
|
> (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
|
|
|
> LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
|
|
> ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
|
|
> (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
|
|
> SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|