These slides were used as a guide for the workshop about Jbake at Greach 2019

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