mraible / jhipster-book

The JHipster Mini-Book

The JHipster 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:

1. Gradle, which will watch the file system and rebuild the HTML version continuously using Asciidoctor

2. 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.

1. Select New site from Git

2. Select your Git provider

3. Select your repository

4. Select the branch to deploy

5. Build command: npm run build:site

6. Publish directory: public/

7. 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://jhipster-mini-book.netlify.app.

jhipster-book's Issues

Update link to PR for enhanced security

Look for text:

See 21-points#3 for all the changes that I needed to make in resource classes and their tests.

Unable to embed fonts in PDF

When InfoQ tried to upload the prepress version of the 7.0.0 release to Lulu, it failed because they were unable to embed the fonts in the PDF.

Related: Lulu's How Do I Embed Fonts in a PDF?

Fix vulnerabilities

# npm audit report

async  <2.6.4
Severity: high
Prototype Pollution in async - https://github.com/advisories/GHSA-fwr7-v2mv-hh25
fix available via `npm audit fix --force`
Will install [email protected], which is a breaking change
node_modules/async
  portscanner  0.1.1 - 2.1.1
  Depends on vulnerable versions of async
  node_modules/portscanner
    browser-sync  <=0.6.2 || >=2.0.0-rc1
    Depends on vulnerable versions of portscanner
    node_modules/browser-sync

convict  <6.2.2
Severity: high
Prototype Pollution in convict - https://github.com/advisories/GHSA-x2w5-725j-gf2g
fix available via `npm audit fix`
node_modules/mini-book-site-generator/node_modules/convict
  @antora/playbook-builder  <=3.0.0-rc.6
  Depends on vulnerable versions of convict
  node_modules/mini-book-site-generator/node_modules/@antora/playbook-builder

glob-parent  <5.1.2
Severity: high
Regular expression denial of service in glob-parent - https://github.com/advisories/GHSA-ww39-953v-wcq6
fix available via `npm audit fix`
node_modules/glob-parent
  glob-stream  5.3.0 - 6.1.0
  Depends on vulnerable versions of glob-parent
  node_modules/glob-stream
    vinyl-fs  >=2.4.2
    Depends on vulnerable versions of glob-stream
    node_modules/vinyl-fs
      @antora/site-publisher  <=3.0.0-rc.6
      Depends on vulnerable versions of gulp-vinyl-zip
      Depends on vulnerable versions of vinyl-fs
      node_modules/@antora/site-publisher
      gulp-vinyl-zip  >=2.1.1
      Depends on vulnerable versions of vinyl-fs
      node_modules/gulp-vinyl-zip

isomorphic-git  <1.8.2
Severity: moderate
Directory Traversal in isomorphic-git - https://github.com/advisories/GHSA-fgxq-p49f-qw99
No fix available
node_modules/isomorphic-git
  mini-book-site-generator  *
  Depends on vulnerable versions of isomorphic-git
  node_modules/mini-book-site-generator

12 vulnerabilities (2 moderate, 10 high)

Rename chapter files from chapter1 to chapter-1, etc

It doesn't matter for book artifacts, but I think it looks better on the website.

Update cover image to reference JHipster 7

Currently, it says JHipster 5.x. #72 (comment)

Typos in text on pages 71/170

it says
Here’s some sudo-code to show the logic

do you mean pseudo instead?

TypeScript and Shell syntax highlighting doesn't work for all formats

formats: HTML, PDF, EPUB

Evaluate Chart.js

https://www.chartjs.org/
https://andrew-flower.com/blog/angular-chartjs