The flavour of Markdown used is pandoc's Markdown. Its specifics and extensions can be examined here: https://pandoc.org/MANUAL.html#pandocs-markdown
Types of documents managed
- 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
.epuboutput (e-book) into
.mobifiles (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.
Generating the documentation
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.
Updating the docs for a new version
To change the version number that appears in the generated docs, update the
project.version property in the
build.gradle script. The
should also be changed to reflect the new date the generated documents should
How the docs are generated
Pandoc is used to convert the Markdown sources into HTML, using the
appropriate HTML template in the
templates directory, which in turn make use
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
documentation from running due to WebKit's same-origin policies being stricter