Asciidoctor EPUB3: A native EPUB3 converter for AsciiDoc
Asciidoctor EPUB3 is a set of Asciidoctor extensions for converting AsciiDoc documents directly to the EPUB3 and KF8/MOBI e-book formats.
Documentation
Detailed installation and usage instructions can be found on the Asciidoctor Docs site.
Installation
Asciidoctor EPUB3 is published on RubyGems.org. Asciidoctor EPUB3 requires Ruby 2.3 or newer. You can install the published gem using the following command:
$ gem install asciidoctor-epub3Assuming the gem and its dependencies install properly, verify you can run the asciidoctor-epub3 script:
$ asciidoctor-epub3 -vIf you see the version of Asciidoctor EPUB3 printed, youโre ready to use Asciidoctor EPUB3.
Usage
Converting an AsciiDoc document to EPUB3 is as simple as passing your document to the asciidoctor-epub3 command.
This command should be available on your PATH if you installed the asciidoctor-epub3 gem.
Otherwise, you can find the command in the bin folder of the project.
We also recommend specifying an output directory using the -D option flag.
$ asciidoctor-epub3 -D output path/to/book.adocWhen the script completes, youโll see the file book.epub appear in the output directory. Open that file with an EPUB3 reader to view the result.
You may also produce KF8/MOBI file by setting ebook-format attribute to kf8.
$ asciidoctor-epub3 -D output -a ebook-format=kf8 path/to/book.adocWhen the script completes, the file book.mobi will appear in output directory.
Contributing
In the spirit of free software, everyone is encouraged to help improve this project.
To contribute code, simply fork the project on GitHub, hack away and send a pull request with your proposed changes.
Feel free to use the issue tracker or {uri-discuss}[Asciidoctor mailing list] to provide feedback or suggestions in other ways.
Development
To help develop Asciidoctor EPUB3, or to simply test drive the development version, you need to get the source from GitHub. Follow the instructions below to learn how to clone the source and run it from your local copy.
Retrieve the Source Code
You can retrieve Asciidoctor EPUB3 in one of two ways:
-
Clone the git repository
-
Download a zip archive of the repository
Option 1: Fetch Using git clone
If you want to clone the git repository, simply copy the {uri-repo}[GitHub repository URL] and pass it to the git clone command:
$ git clone {uri-repo}
Next, change to the project directory:
$ cd asciidoctor-epub3
Option 2: Download the Archive
If you want to download a zip archive, click on the btn:[[cloud download] button on the right-hand side of the repository page on GitHub. Once the download finishes, extract the archive, open a console and change to that directory.
|
Tip
|
Instead of working out of the asciidoctor-epub3 directory, you can simply add the absolute path of the bin directory to your PATH environment variable.
|
Weโll leverage the project configuration to install the necessary dependencies.
Prepare RVM (optional step)
If youโre using RVM, we recommend creating a new gemset to work with Asciidoctor EPUB3:
$ rvm use 2.2@asciidoctor-epub3-dev --create
We like RVM because it keeps the dependencies required by various projects isolated.
Install the Dependencies
The dependencies needed to use Asciidoctor EPUB3 are defined in the Gemfile at the root of the project. We can use Bundler to install the dependencies for us.
To check if you have Bundler available, use the bundle command to query the version installed:
$ bundle --version
If itโs not installed, use the gem command to install it.
$ gem install bundler
Then use the bundle command to install the project dependencies:
$ bundle
|
Note
|
You need to call bundle from the project directory so that it can find the Gemfile.
|
Build and Install the Gem
Now that the dependencies are installed, you can build and install the gem.
Use the Rake build tool to build and install the gem (into the current RVM gemset or into the system if not using RVM):
$ rake install:local
The build will report that it built the gem into the pkg directory and that it installed the gem.
Once the development version of the gem is installed, you can run Asciidoctor EPUB3 by invoking the asciidoctor-epub3 script:
$ asciidoctor-epub3 -v
If you see the version of Asciidoctor EPUB3 printed to your console, youโre ready to use Asciidoctor EPUB3!
Shortcut: Run the Launch Script Directly
Assuming all the required gems install properly, you can run the asciidoctor-epub3 script directly out of the project folder using either:
$ bin/asciidoctor-epub3 -v
or
$ bundle exec bin/asciidoctor-epub3 -v
Youโre now ready to test drive the development version of Asciidoctor EPUB3!
Jump back to [Getting Started] to learn how to create an AsciiDoc document and convert it to EPUB3.
Fonts
Asciidoctor EPUB3 embeds a set of fonts and font icons. The themeโs fonts are located in the data/fonts directory.
The M+ Outline fonts are used for titles, headings, literal (monospace) text, and annotation numbers. The body text uses Noto Serif. Admonition icons and the end-of-chapter mark are from the Font Awesome icon font. Refer to the NOTICE.adoc file for further information about the fonts.
Planned Features and Work In Progress
See WORKLOG.adoc.
Authors
Asciidoctor EPUB3 was written by Dan Allen and Sarah White of OpenDevise on behalf of the Asciidoctor Project.
Copyright
Copyright ยฉ 2014-2021 OpenDevise Inc. and the Asciidoctor Project. Free use of this software is granted under the terms of the MIT License.
For the full text of the license, see the LICENSE file. Refer to the NOTICE.adoc file for information about third-party Open Source software in use.