Thymeleaf documentation in Markdown format, which is then converted to HTML, EPUB (using Pandoc), MOBI (using Calibre) and PDF (using wkhtmltopdf) formats using the supplied Gradle build script.
The flavour of Markdown used is pandoc's Markdown. Its specifics and extensions can be examined here: https://pandoc.org/MANUAL.html#pandocs-markdown
- Tutorials, living in
docs/tutorials
. Output: HTML, PDF, EPUB and Kindle. Given their length, tutorials use their own HTML style, with an index frame on the left side. - Articles, living in
docs/articles
. Output: HTML only. Articles are output with the same HTML style as the rest of the Thymeleaf web site.
Java 8+ required. The build process is often run on machines with Java 11.
- Download and install Gradle: http://www.gradle.org/install
- Download and install Pandoc: http://johnmacfarlane.net/pandoc/installing.html (PDF output is not done using Pandoc, so you don't need to get LaTeX.). You will need version 2.2.1 or newer.
- Optional: download and install wkhtmltopdf: http://wkhtmltopdf.org/downloads.html. wkhtmltopdf is used for rendering PDF files from pandoc's HTML output.
- Optional: download and install Calibre: http://calibre-ebook.com/download.
Calibre is used for conversion of pandoc's
.epub
output (e-book) into.mobi
files (Kindle format).
Additionally, if you want to be able to import this project into Eclipse or run the Gradle tasks from Eclipse, then install the Groovy-Eclipse and Gradle IDE components from the Spring Tool Suite. IntelliJ IDEA has support for Gradle tasks through its built-in Gradle plugin.
Use the Gradle build script to generate the documentation from the Markdown sources to HTML, e-books and PDF. The following Gradle tasks perform these jobs:
generateDocsHTML
- Create the HTML docs.generateDocsPDF
- Create the PDF docs (also creates the HTML docs since it depends on them)generateDocsEbook
- Create the e-books.generateDocs
- Creates all docs
The generated docs will end up in the build/site/doc
directory. The entire
build/site
directory will be prepared for direct copy (cp -R
) to the
Thymeleaf website repository (thymeleaf.github.com
) for publishing.
To change the version number that appears in the generated docs, update the
project.version
property in the build.gradle
script. The documentDate
var
should also be changed to reflect the new date the generated documents should
refer to.
Pandoc is used to convert the Markdown sources into HTML, using the
appropriate HTML template in the templates
directory, which in turn make use
of JavaScript and CSS files copied from the scripts
and styles
directories.
Pandoc is also used to generate e-books in EPUB format.
Calibre is used to convert e-books to MOBI (Kindle) format.
wkhtmltopdf is used to create PDF versions of the HTML docs based on the
media="print"
stylesheet instead of the media="screen"
one you normally see
when opening it in your browser. The PDF generation task also launches a
Jetty server to host the HTML files since wkhtmltopdf uses WebKit and
not using a server would prevent many of the JavaScript files in the HTML
documentation from running due to WebKit's same-origin policies being stricter
with the file://
protocol.