This document provides an overview of a JBake workshop. The schedule includes an introduction to JBake, basic commands, creating blog content with templates, custom content types, Asciidoctor extensions, and integrating JBake with an open source project using Gradle. Attendees will learn how to install JBake, generate static sites, include code samples in blog posts, and integrate Javadoc documentation into the generated sites.

1. JBake Workshop
Mario Garcia

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
● ….

7. Installation
Who hasn’t installed JBaked yet ?

8. Installation
Who hasn’t installed JBaked yet ?

9. ● Prerequisites
○ JDK 8
● Three scenarios
○ Download BINARY directly
○ Install via SDKMAN command line (sdkman.io)
○ Integrate with your favourite BUILDING TOOL
Installation

10. SDKMAN
● Install sdkman (https://sdkman.io/install)
● Then “sdk install jbake”

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

14. Get used with the basics

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

17. Create a new blog

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

20. About Groovy templates

21. About Groovy templates
● No need for enclosing tag. Braces mark the scope

22. About Groovy templates
● Plain strings can be inserted using yield or yieldUnscaped

23. Lets create a new entry

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:

27. https://asciidoctor.org/docs/asciidoc-syntax-quick-reference

28. Then bake it and serve it locally
● Execute with -s (it does bake and serve altogether)
○ jbake -s

29. Modifying templates

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

34. Custom content

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>

36. Videos

37. Asciidoctor Extensions

38. Asciidoctor extensions
● Add extra features to your entries adding extension such as:
○ Comments
○ Render mathematical formulas
○ Diagrams
○ QR Code
○ ...

39. Asciidoctor Diagram
● Already added to JBake
● We have to enable it in the jbake.properties

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

43. Add a site to our OSS project

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

46. Clone project
git clone https://github.com/mariogarcia/jbake_greach.git

47. Add JBake plugin
● In your build.gradle.kts

48. Add source code in 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

50. Include source code in documentation
● Use asciidoctor include directive

51. Access javadoc from site

52. Include javadoc
● Generate javadoc
● Copy javadoc to jbake output dir
● Add link to javadoc index.html page

53. Include javadoc (cont.)

54. Include javadoc
● Link it from documentation.adoc
● It’s just a relative link to javadoc/index.html

55. Include javadoc

56. Add Disqus

57. Add Disqus
● Add Puravida Extensions

58. Add Disqus
● Add disqus directive to documentation.adoc
○ Check https://puravida-software.gitlab.io/asciidoctor-extensions

59. Integrate asciidoc

60. Asciidoctor user guide
● Add asciidoctor plugin

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

62. Asciidoctor

63. Asciidoctor

64. Summary

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