This is an awesome book. It’s written in AsciiDoc and compiles to HTML, PDF, and EPUB using the Asciidoctor Gradle plugin.
To convert this book to HTML and EPUB, run the following command:
npm run build
-
Open build/asciidoc/html5/index.html in your browser to see the generated HTML file.
-
Open build/asciidoc/pdf-prepress/index.pdf to see the 6x9" printable PDF file.
-
Open build/asciidoc/pdf-screen/index.pdf to see the downloadable 8.5x11" PDF file.
-
Open build/asciidoc/epub3/index.epub in iBooks to see the generated EPUB file.
If you’d like a very pleasant authoring experience, the project provides build files that make it possible. First of all,
you’ll need to run gradlew once. After running it once, you can run ./gradlew watch to watch for any changes and
recompile files as you save them.
To have a similar awesome experience (watch and auto-reload) in your browser, install Node.js on your machine.
After installing Node, you can run the following command to install development tools (like Browsersync).
npm install
|
Tip
|
You will only need to run this command when dependencies change in package.json.
|
Now you can run the following command:
npm run watch
This will start two daemons:
-
Gradle, which will watch the file system and rebuild the HTML version continuously using Asciidoctor
-
BrowserSync, which will serve the updated HTML version all of the time and make it available over HTTP
Thanks to this, you’ll have a constantly up to date HTML version available in your browser while editing.
To update the dependencies in build.gradle, run:
./gradlew useLatestVersions
To update the dependencies in package.json, install npm-check-updates and run it:
npm i -g npm-check-updates ncu
This project includes GitHub action workflows to build and publish the book (PDF, EPUB, HTML). To trigger this, you have two options:
-
Run the following script:
npm run release -
Use GitHub’s UI to create the release from your book repository
Once completed, the publish workflow will attach the generated files to the release page.
The benefit of the release npm script is that the version will be updated automatically in the package.json and version.txt files. The version will be reflected in the generated files because the version in version.txt is used as the Gradle project version when building the book.
Note that in order for the release npm script to work, you’ll need to make sure that a GITHUB_TOKEN environment variable is available, as explained in [release-it’s documentation](https://github.com/release-it/release-it/blob/master/docs/environment-variables.md).