mraible / infoq-mini-book Goto Github PK

View Code? Open in Web Editor NEW

174.0 13.0 78.0 34.9 MB

Template project for creating an InfoQ Mini-Book with Asciidoctor

Home Page: https://infoq-mini-book.netlify.app

License: Apache License 2.0

JavaScript 11.01% CSS 77.62% Ruby 10.70% HTML 0.37% Handlebars 0.31%

infoq asciidoctor gradle asciidoc

infoq-mini-book's Introduction

An InfoQ Mini-Book

This is an awesome book. It’s written in AsciiDoc and compiles to HTML, PDF, and EPUB using the Asciidoctor Gradle plugin.

Installing

npm run setup

Building

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.

To generate a static site using Antora, run the following command:

npm run build:site

Sweet Authoring Experience

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.

Similarly, you can run the following command to continuously watch the file system and rebuild the static site:

npm run watch:site

Update Dependencies

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

Releasing/Publishing

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.

Deploy to Netlify

To deploy this repository to Netlify, create an account and log in.

Select New site from Git
Select your Git provider
Select your repository
Select the branch to deploy
Build command: npm run build:site
Publish directory: public/
Click Deploy site

Your site should take less than a minute to deploy, depending on the size of your book.

Netlify Preview

This repository is using a netlify.toml configuration file to build and publish the static site to Netlify. You can see the result at: https://infoq-mini-book.netlify.app/.

infoq-mini-book's People

Contributors

Stargazers

Watchers

Forkers

luiz158 nebrass atomfrede jensworkgit willis7 flanciskinho ahnan4arch payne ksushik myr1782 danhaywood nordinh digideskio humboldtux-tmp wanatchapong ivan-tamayo jbravo emmanuelbernard adib-samples kodejava shankardevy kharmaodo kandyjam nixdorf66 rongfengliang lldmz wimdeblauwe theuncanny wsaryada velibormitic joshlong-attic gcdr fingergit otoukebri cchacin min2ha mojavelinux heldermorais chandanws sizovs lurch sascha-frinken kensipe mcpringle kabutz funcguy johnsgp gdouzwt marcobehler bernedom mauriziocasciano sbaldrich dsebastien foxgem matsev ppreeper ggrossetie willcor marcelomata batate dolfino mansourtine mandeepsmagh wheredevel thst71 dattatray-gund k8s-ossc alexrogalskiy jswamy-aires saiupadhyayula sivaprasadreddy kbllr mwithiga

infoq-mini-book's Issues

No cross reference links in generated pdf file

There are no cross reference links for included chapters in the generated pdf document. It's just text.

Also all items in TOC are not clickable.

Just to make it clear, cross reference links are working fine in the epub, however I'm not sure if it's an issue of the asciidoctor.

Switch syntax highlighting to Rouge

Now that Asciidoctor 2 supports Rouge, and Rouge is already supported by Asciidoctor PDF, I recommend switching to it.

Question: how to run this project in Windows

I was able to run the build.sh in Linux successfully. But Is there an equivalent batch command that I can run in Windows? Thanks!

Figure and listing numbers not consistent between formats

When I generate HTML, PDF and EPUB versions, the figure and listing numbers for the EPUB version are not consistent with the other two.

Figure numbers flow through the whole document for HTML and PDF, but are reset at each chapter boundary (restart from Figure 1) for EPUB.

Listing numbers are missing for HTML and PDF, but are added for EPUB. If they are added manually in the adoc files, they are then duplicated in the EPUB. They are also reset to 1 in the EPUB, resulting in captions like this one at the beginning of chapter 2:

Listing 1. Listing 2.1 Caption

The easiest way to see this is to clone my fork of this repo, setup gem bundler as described in README and run build.sh, then review the following three files:

build/asciidoc/epub3/index.epub
build/asciidoc/html5/index.html
build/asciidoc/pdf/index.pdf

All chapters titles are the book titles in the epub file

Actually the issue is in title.

After generating epub all chapter titles are the book titles.

Update to match JHipster Book 2.0 with Gulp

Minor release issue

Hello Matt,

In my repo, I've integrated the github publish action, but encountered a problem with my release workflow.
With it, I simply use git tag x.y.z then git push --tags. Unfortunately, when doing that, the upload-assets action fails with a pretty hard to understand error: "Not Found".

It seems to be a known issue: alexellis/upload-assets#2

To fix this, I've adapted the publish.yml file as follows in my repo:

      - name: Rename files
       ...
      - name: Create Release
        id: create_release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref }}
          draft: false
          prerelease: false
          body: |
            w00t, almost there!
      - name: Upload release assets
        uses: alexellis/[email protected]
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          asset_paths: '["build/{*.pdf,*.epub,*.zip}"]'

As you can see, it's pretty much the same as before, apart from the fact that I've added a "Create Release" job, which creates a Github release along the way. Thanks to that, the release is created before the upload-assets action executes and it then works as expected.

I haven't created a PR, because I don't know if this behavior is intended for everyone; but I thought that it might be of use to others.

Unable to generate PDF

I am trying to use generate-pdf.sh to generate a PDF, but it does not work.

I first ran rvm install "ruby-2.3.1" to install the required Ruby version. But then things failed with:

To install the version of bundler this project requires, run gem install bundler -v '< 2'

So I ran gem install bundler -v '< 2', but now I get:

Bundler::GemNotFound: Could not find Ascii85-1.0.3 in any of the sources
  /Users/wdb/.rvm/gems/ruby-2.3.1/gems/bundler-1.16.1/lib/bundler/spec_set.rb:88:in `block in materialize'
  /Users/wdb/.rvm/gems/ruby-2.3.1/gems/bundler-1.16.1/lib/bundler/spec_set.rb:82:in `map!'
  /Users/wdb/.rvm/gems/ruby-2.3.1/gems/bundler-1.16.1/lib/bundler/spec_set.rb:82:in `materialize'
  /Users/wdb/.rvm/gems/ruby-2.3.1/gems/bundler-1.16.1/lib/bundler/definition.rb:170:in `specs'
  /Users/wdb/.rvm/gems/ruby-2.3.1/gems/bundler-1.16.1/lib/bundler/definition.rb:237:in `specs_for'
  /Users/wdb/.rvm/gems/ruby-2.3.1/gems/bundler-1.16.1/lib/bundler/definition.rb:226:in `requested_specs'
  /Users/wdb/.rvm/gems/ruby-2.3.1/gems/bundler-1.16.1/lib/bundler/runtime.rb:108:in `block in definition_method'
  /Users/wdb/.rvm/gems/ruby-2.3.1/gems/bundler-1.16.1/lib/bundler/runtime.rb:20:in `setup'
  /Users/wdb/.rvm/gems/ruby-2.3.1/gems/bundler-1.16.1/lib/bundler.rb:107:in `setup'
  /Users/wdb/.rvm/gems/ruby-2.3.1/gems/bundler-1.16.1/lib/bundler/setup.rb:20:in `<top (required)>'
  /Users/wdb/.rvm/rubies/ruby-2.3.1/lib/ruby/site_ruby/2.3.0/rubygems/core_ext/kernel_require.rb:55:in `require'
  /Users/wdb/.rvm/rubies/ruby-2.3.1/lib/ruby/site_ruby/2.3.0/rubygems/core_ext/kernel_require.rb:55:in `require'
Could not find Ascii85-1.0.3 in any of the sources
Run `bundle install` to install missing gems.
./generate-pdf.sh: line 55: bundler:: command not found

So I ran bundle install

And now I get:

asciidoctor: WARNING: skipping reference to missing attribute: snippetsdirectory
asciidoctor: WARNING: skipping reference to missing attribute: snippetsdirectory
/Users/wdb/Projects/infoq-mini-book/.bundle/gems/ruby/2.3.0/bundler/gems/asciidoctor-pdf-03ceac32e426/bin/optimize-pdf: line 51: gs: command not found

What is this gs command and how do I install it?

Tags in XML files not working

I have a working Gradle build that generates a PDF from my asciidoc sources. This includes some references to XML files with tags and those are working fine.

I am now trying to migrate my content to use this template, but none of the includes that point to XML files are working. Includes to Java files for example are all fine.

My build is using org.asciidoctor:asciidoctor-gradle-plugin:1.5.7 while this templates uses org.asciidoctor:asciidoctor-gradle-plugin:1.5.3. However, when I downgrade my project, the XML includes with tags keep working.

The path to the XML file itself is certainly correct, because when I replace the [tags=foo] with [] to display the full file, the HTML export has the full contents of the file. (I use build.sh to create the HTML file)

How to define "parts" for the PDF?

I am now able to build my book for PDF, HTML and epub. However, I notice that the PDF export has these big "PART ONE" titles at the start of each chapter. Can I remove those easily as there is no need to divide the book in parts?

Cross reference links not working for html

Cross reference links to included chapters are not working for html.

Just an example.

chapter01.adoc
[#chapter01]
= Chapter 01
...

glossary.adoc
a term <<chapter01#chapter01>>

In the generated index.html the link points to chapter01.html#chapter01, but chapter01.html doesn't exist.

By using just <> everything works for html document, but not for epub anymore.

Don't hardcode env var KINDLEGEN in build.sh

It will give false assumption when building even though KINDLEGEN is correctly setup.

I got this error when building :

Caused by: org.jruby.exceptions.RaiseException: (LoadError) no such file to load -- kindlegen
        at org.jruby.RubyKernel.require(org/jruby/RubyKernel.java:961)
        at RUBY.require(uri:classloader:/META-INF/jruby.home/lib/ruby/stdlib/rubygems/core_ext/kernel_require.rb:54)
        at RUBY.distill_epub_to_mobi(uri:classloader:/gems/asciidoctor-epub3-1.5.0.alpha.7/lib/asciidoctor-epub3/packager.rb:611)
        at RUBY.package(uri:classloader:/gems/asciidoctor-epub3-1.5.0.alpha.7/lib/asciidoctor-epub3/packager.rb:602)
        at RUBY.write(uri:classloader:/gems/asciidoctor-epub3-1.5.0.alpha.7/lib/asciidoctor-epub3/converter.rb:41)
        at RUBY.write(uri:classloader:/gems/asciidoctor-1.5.6.1/lib/asciidoctor/document.rb:1083)
        at RUBY.convert(uri:classloader:/gems/asciidoctor-1.5.6.1/lib/asciidoctor.rb:1507)
        at RUBY.block in convert_file(uri:classloader:/gems/asciidoctor-1.5.6.1/lib/asciidoctor.rb:1575)
        at org.jruby.RubyIO.open(org/jruby/RubyIO.java:1156)
        at RUBY.convert_file(uri:classloader:/gems/asciidoctor-1.5.6.1/lib/asciidoctor.rb:1575)
        at RUBY.convertFile(<script>:75)

Add ability to link to downloads

@Mogztter You sent me a prototype a while back that had a heading at the top that allowed you to link to the artifact downloads (e.g. PDF, EPUB). Do you think it'd be possible to add that to this template?

I'd be happy to pay for your services to implement this feature.

Which version of Ruby to use?

Sorry if this is a dumb question, but I'm entirely new to the Ruby ecosystem...

The README in this project says:

To be able to generate the PDF, you need have some dependencies installed.

On macOS, run the following commands:

rvm install "ruby-2.3.1"
gem install bundler -v '< 2'
bundle install

I'm running on Ubuntu 14.04 and so I did the 3 lines above, and then ./generate-pdf.sh errors with:

Could not find Ascii85-1.0.3 in any of the sources
Run `bundle install` to install missing gems.
Could not find Ascii85-1.0.3 in any of the sources
Run `bundle install` to install missing gems.

So then I tried switching my "default Ruby" (?) with rvm use ruby-2.3.1 and running the above three commands again, but now bundle install errors with:

Fetching gem metadata from https://rubygems.org/.........
geom2d-0.2.0 requires ruby version >= 2.4, which is incompatible with the
current version, ruby 2.3.1p112

And after this I've got no idea what to try next!!

Download Kindlegen automatically as part of the build

Suggestion from @mojavelinux:

One thing that would be really nice is to have Kindlegen downloaded automatically as part of the build. Because of the Kindlegen license, we can't distribute it, but we can get Gradle to go fetch it for us. Rob Winch put together a task to do this:

https://github.com/rwinch/asciidoctor-gradle-examples/blob/kf8/asciidoc-to-epub3-kf8-example/build.gradle

npm build scirpt only works on Bash shell

There is a build and clean script in the package.json, but it is bash specific, can not work in Powershell/Windows system.

Building & releasing multiple books

Hi @mraible,

For my current project, I've adapted the GH action pipeline to support building/attaching multiple books to a release.
Would that be of interest to include here?

Here's the gist of it:

files have a specific prefix instead of a generic index.adoc name: book_<Whatever>.adoc
the publish.yml file looks for files whose name starts with book_
once the files are identified, the <Whatever> part is extracted and used in the cp command

Here's my current publish.yml file:

name: Publish

on:
  push:
    tags:
      - '*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-java@v1
        with:
          java-version: 11
      - name: Build book
        run: npm run setup
      - name: Get release version
        run: echo "RELEASE_VERSION=${GITHUB_REF#refs/*/}" >> $GITHUB_ENV
      - name: Rename files
        run: |
          find ./build -type f -name "book_*.*" | while read fname; do
            dirname=`dirname "$fname"`
            foldername=`basename "$dirname"`
            filename=`basename "$fname"`
            extension="${filename##*.}"
            # Reference: https://stackoverflow.com/questions/428109/extract-substring-in-bash
            filename_without_extension="${filename%.*}"
            bookname=$(echo $filename_without_extension| cut -d'_' -f 2)
            echo "dirname: ${dirname}"
            echo "foldername: ${foldername}"
            echo "filename: ${filename}"
            echo "extension: ${extension}"
            echo "filename without extension: ${filename_without_extension}"
            echo "bookname: ${bookname}"
            echo "--------------------------"
            echo "Copying and renaming..."
            cp "${dirname}/${filename}" "./build/${{ github.event.repository.name }}-${bookname}-${foldername}-${{ env.RELEASE_VERSION }}.${extension}"
            echo "Done!"
            echo "--------------------------"
          done
          cd ./build/asciidoc/html5
          zip -r ${{ github.event.repository.name }}-html5-${{ env.RELEASE_VERSION }}.zip **
          mv *.zip ../..
          cd ../..
          ls
      - name: Upload release assets
        uses: alexellis/[email protected]
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          asset_paths: '["build/{*.pdf,*.epub,*.zip}", "Mindmap.mm"]'

License for this repo

Hi, I love this work. But, can you clarify the license for this project?

Thanks!