2. Me
● Mario Garcia
● Working at Kaleidos.net
● Mostly Backend Developer (Java, Groovy)
● Some Frontend lately (React, Vue, CSS still not my thing)
3. Schedule
● What is JBake and use cases
● Installation
● Basic commands
● Blog
○ Create content
○ Templates
○ Custom content
○ Asciidoctor extensions
○ Push it to Github
4. Schedule
● Break (15 min)
● Project OSS
○ Some code in Gradle project
○ Configure bake
○ Include javadoc
○ Include asciidoctor doc
5. What is JBake
“JBake is a Java based, open source, static site/blog
generator for developers & designers”
6. Some features
● Self contained
● Integrated with other build tools (Gradle, Maven, SBT…)
● Content formats (asciidoctor, markdown, html)
● Multiple template support
● Draft support
● ….
9. ● Prerequisites
○ JDK 8
● Three scenarios
○ Download BINARY directly
○ Install via SDKMAN command line (sdkman.io)
○ Integrate with your favourite BUILDING TOOL
Installation
11. Download binary
● Go to https://jbake.org/download.html
● Click on the latest distribution
● Decompress the zip wherever you want
● Make sure the jbake command is available in your console path
○ If you’re in linux e.g. modify .bashrc to add jbake command to the $PATH
12. Integrate with your build tool
We’ll see an example in the second part of this workshop
with Gradle
13. Use your favourite IDE
● Use any IDE with syntax highlight for
○ Asciidoctor
○ Markdown
○ HTML
○ Groovy
15. Basic commands
● We’re still playing so create a temporary folder
○ Check JBake help
■ jbake --help
○ Create folder nameofproject
■ jbake -i <nameofproject>
○ Browse the structure with your favourite editor
16. Basic commands
● Bake content to get html
○ Get into the <nameoftheproject> folder then execute
■ jbake -b
○ That will produce the final output of the blog, to browse it as if it were published online, do:
■ jbake -s
18. Create greachblog
● Create the new project using Groovy MTE as template engine
○ jbake -i -t groovy-mte greachblog
● Lets comment on the structure and templates a little bit
19. Structure
● Directories
○ assets: css, js, images…
○ content: asciidoctor, markdown or html files
○ templates: Templates to interpret content files and produce the final ouput result
● jbake.properties
○ JBake configuration
24. Open the project in your favourite editor
● Mines are (the ones I can help you with)
○ Emacs
○ IntelliJ
● But any editor should work.
● Look for plugins/extensions that could help you rendering/highlighting Markdown or Asciidoctor
syntax
25. Asciidoctor
● “A fast text processor & publishing toolchain for converting AsciiDoc to HTML5, DocBook &
more”.
○ Asciidoctor: https://asciidoctor.org/
○ Syntax Reference: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference
26. Create an entry for today
● Create an asciidoctor file
○ greachblog/content/2019/03/28/greach_jbake_workshop.adoc
● Copy the following content:
30. I don’t see my name in the entry
● We would like all blog entries to show the name of the author
● What do we need ?
○ Know about the JBAKE DATA MODEL
○ Modify the template to add the property author
○ Bake it again
31. JBake Data Model
● Global variables: These data variables are available to all templates regardless of the type.
● Page / Post / Custom: Variables for predefined templates as well as any custom templates you
created yourself
● Index: The index template has extra data variables available to it related to paging
● Tags: Data related to published tagged documents
https://jbake.org/docs/2.6.4/#data_model
32. Add the author
● Task 1
○ Go to post-brick.tpl and add the author somewhere
○ Check JBake post related variables https://jbake.org/docs/2.6.4/#data_model
33. ● Task 2
○ I would like to write code in its own source file and then show it partially in the blog entry. I also want to be
able to download the sample code
■ You can add a :metaproperty: in the asciidoc document header called attached with the name of the
script
■ Add the script at the same place as the asciidoc document
■ Add an href in the header to “download” the attached document getting the name from the post
headers
Attach code to entry
35. Pages, Posts, Tags… Videos ?
● Create a new template named videos.tpl
● The new content of type video should set it in the content file header :type:
● We will pass the youtube video id to the template via content header :video:
● If you want to add a new type of content you should associate the new type of templates in
jbake.properties
○ template.<newtype>.tpl=<nameofthetemplate>
38. Asciidoctor extensions
● Add extra features to your entries adding extension such as:
○ Comments
○ Render mathematical formulas
○ Diagrams
○ QR Code
○ ...
40. Create a diagram
● In your asciidoctor content files write a ditaa diagram:
41. Add Disqus
● Puravida extensions
○ https://puravida-software.gitlab.io/asciidoctor-extensions/
● Add the following inline directive to your content file
Replace asciidoctor-extensions with the id you registered in Disqus.com
42. More extensions
● Asciidoctor site extension list
○ https://asciidoctor.org/docs/extensions/
● Puravida extensions
○ https://gitlab.com/puravida-software/asciidoctor-extensions
44. JBake integrates with build tools
● I’ve got an OSS project and I would like to create the project’s site
○ The project is already using a build tool
○ The project already generates different types of docs you’d like to link from the site
■ Javadocs, using guides...etc
● In this case I’ll be using Gradle
○ www.gradle.org
45. OSS Project
● Simple Gradle Java Project
○ Site
○ Javadoc
● I would like it to have its own site and integrate the javadoc in it
● Show some source code in the web site
49. Make asciidoctor content files aware...
● You need to pass where the source files are to being able to include them in the web page
○ Set configuration.asciidoctor.attributes
61. Asciidoctor
● Generate content (modify src/main/index.adoc) and then
○ ./gradlew ascii
● Copy generated output to jbake output
○ from build/asciidoc/html5
○ into build/jbake/guide
● Include relative link to user guide in documentation.adoc
65. Summary
● Jbake great for create blog content or micro sites
● Good integration with existing build tools
● Good integration with asciidoctor
● I hope you liked it