Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rcmoutinho/ebook-with-asciidoctor

Free and Open Source code to automate your ebook! Get your .pdf, .epub, and .mobi in seconds running a single command! Clone this project and start your eBook today!
https://github.com/rcmoutinho/ebook-with-asciidoctor

asciidoctor automation docker ebook

Last synced: 7 days ago
JSON representation

Free and Open Source code to automate your ebook! Get your .pdf, .epub, and .mobi in seconds running a single command! Clone this project and start your eBook today!

Awesome Lists containing this project

README 

        
= Launch your best content today! Free and Open Source code to automate your ebook!



image:https://img.shields.io/travis/com/rcmoutinho/ebook-with-asciidoctor.svg[Travis (.com)] image:https://img.shields.io/github/release/rcmoutinho/ebook-with-asciidoctor.svg[GitHub release] image:https://img.shields.io/github/issues/rcmoutinho/ebook-with-asciidoctor.svg[GitHub issues] image:https://img.shields.io/github/license/rcmoutinho/ebook-with-asciidoctor.svg[GitHub License]



To create your own ebook is super simple: clone this project and start writing!



[NOTE]

--

And now you don't need to worry about the release process because *it's fully automated!* Follow all the instructions from https://github.com/rcmoutinho/automated-release[automated-release] project and config your onw project.



This configuration optional. You can stay releasing manually your ebook if you want. 



Basically you only need to configure you https://github.com/rcmoutinho/automated-release#github[GitHub Personal Access Token] and https://github.com/rcmoutinho/automated-release#travis-ci[enable Travis-CI]. Ok! Now you are going to need Node.js installed to make sure you are respecting _conventional-commits_ pattern. But again, the automated versioning is optional.



Take a look at all the automated releases generated by those https://github.com/rcmoutinho/automated-release/pulls?q=is%3Apr+is%3Aclosed[Pull Requests] and the good looking https://github.com/rcmoutinho/automated-release/releases[release page]. You only need to write good commits to have all this. :smile:



The https://github.com/rcmoutinho/ebook-with-asciidoctor/releases[latest release] (or maybe the first one o/) of this project is already automated.

--



== Getting Started in One Minute



. Clone the project

+

----

git clone https://github.com/rcmoutinho/ebook-with-asciidoctor.git

----



. Generate the eBook

+

----

docker-compose run --rm ebook

----



*DONE!*



.Check your eBook on the `book-release` folder.

image::imgs-readme/book-files.png[Project Files]



.Overview from PDF format

image::imgs-readme/overview.png[Overview from this automated eBook]



== Configure Your eBook



Although the project has lots of configuration, you just need to focus on the following topics:



. Fill the file `automated-ebook.asc` with the right information. Here you will need to change the book name, author, and maybe the number of levels on the table of contents (`:toclevels:`, the default is configured to 3).

. At the same file, adjust chapters file names. You can add, remove or rename. You are in charge here.

. Last but not least, create your chapters! The first chapter has lots of tips about how to deal with Asciidoctor syntax, but you can also check the documentation to get more details.



You can also change the file `cover.png` with your own book cover. The size of this image is _1050x1600_. You can use https://www.canva.com[canva.com] to create your design. *It's FREE.* But the default size there is _1410x2250_, so you will need to resize and fit after downloading (not a problem).



== Generate Your eBook



To simplify things, let's use Docker to automate book generation. Make sure you have it installed.



Each file from the eBook (HTML, Epub, Mobi e PDF) will be generated by using the image https://github.com/asciidoctor/docker-asciidoctor[oficial image of Asciidoctor]. Super easy!



Execute one of the following commands, according to your OS, on the project's root folder:



[source,shell]

----

# linux / unix

docker run --rm -v $(pwd):/documents/ asciidoctor/docker-asciidoctor scripts/docker-startup.sh



# others (change  with the full path of the current directory)

docker run --rm -v :/documents/ asciidoctor/docker-asciidoctor scripts/docker-startup.sh

----



Or use Docker Compose command to be able to type faster and avoid all parameters (already configured on `docker-compose.yml`):



[source,shell]

----

docker-compose run --rm ebook

----



== More about Asciidoctor



* https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[AsciiDoc Syntax Quick Reference] -> The fastest way to get tips from how to use ASC syntax.

* https://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDoc Writer’s Guide] -> Going deeper about ASC details.

* https://asciidoctor.org/docs/asciidoctor-epub3/[Asciidoctor EPUB3] -> Getting curious about how ASC generate book formats.

* https://asciidoctor.org/docs/user-manual/[User Manual] -> OK! Here it is everything about this awesome tool!!



== Projects Using This Format



* https://github.com/duke-certification/java6-to-java8[java6-to-java8] / https://github.com/duke-certification/java6-to-java8-en[java6-to-java8-en]

* https://github.com/cyborgdeveloper/cyborg-developer-cookbook[cyborg-developer-cookbook]



Send a Pull Request with your project's URL that uses this project :smile:



== References



The project https://github.com/progit/progit2[progit2] was used as a reference to create this step-by-step process to automate this ebook. The reference's ebook is available at https://git-scm.com/book/en/v2[git-scm.com/book].