The web site of Apache Shiro is in ongoing transformation to use jbake instead of scms. Some thoughts about the whys and hows (and what was great about SCMS).
The old: SCMS
Let's start with an overview what was great about SCMS.
The good about scms
SCMS is short for Simple Content Management System, and it is really that. A small Java 6 application, which will render content in a lot of formats.
The special thing about scms is that it can render contents multiple times: Just name a file tutorial.md.vtl and will first render it using velocity templates, then using a markdown renderer.
The second great thing: It was written partly in Groovy and was configurable using Groovy Slug - the same config files you use for Jenkins today!
The drawbacks about SCMS
While this did the trick for most of our needs, we had no IDE completion or syntax highlighting, and reading a mix of markdown and velocity without any syntax highlighting was just cruel.
Add to this that there is no configuration specification. For anyone who has never edited Groovy configuration files, they might be confusing at first.
To add to this, we (the Apache Shiro Team) are basically the only users of scms. This means there is no community support. While I tried to rewrite SCMS to have more customization options, markdown support, etc., there was little to no interest of any kind of community. The current state of my fork is: broken. It does not retain the data model correctly, and I was unable to fix this.
Switching to JBake
Now, if you want to attract developers, something had to be done. We discussed various options on the mailing list and decided to give jbake a try. Reasons are mostly: Community support is good enough, it is written in Java (so we can debug it if needed) and it is mature.
The other options were hugo and jakyll, which we will keep in mind in case jbake does not fit our needs.
JBake -- Bootstrap 3??
After starting a new fork for jbake, I found out that jbake still uses bootstrap 3. Bootstrap 3 is quite old and Bootstrap 5 was just released earlier this year (2021). I used an updated version of Bootstrap 3 for a while and decided early to update to Bootstrap 5. If you don't do it early, you will probably never do it. 😉
The nice thing is that jQuery is gone for good. Our custom javascript only consists of three calls or so which could be rewritten to use an id selector instead of a class. We use it to show a "edit this page on github" link as shown in the screenshot below.
Porting over news
We had a special set up with news. As scms was not able to do pagination, we just had one big news page and copied the news as HTML over and over again. We then did the same for the front page (the small news box) which just linked to news.html. JBake, as any modern static site generator, allows pagination and individual articles automatically linked.
The best thing about this approach is that we can now have a list of current news on the front page without the need to maintain it: https://github.com/apache/shiro-site/blob/7177acebd5921415da8231e37b731742b491e978/jbake/templates/index.ftl#L119-L126
Porting over articles and pages
The easiest thing in the transition progress is probably porting over articles. They are mostly text and usually do not require any variables to be interpreted. You can even keep the Markdown file format -- just change the header and you are good!
There was one exception: The Shiro 10-minute-tutorial (and a few others) had variables, which I needed to fill from freemarker. But luckily, there is a trick to replace any variables found in a string (the rendered HTML content):
<@content.body?interpret />Manual corrections
There were some corrections I needed to make when converting markdown to Asciidoc. I used the IntelliJ Asciidoctor-plugin most of the time, but as we had two specialities in our markdown files, we had some manual steps.
HTML link in headings
Some Markdown headings had an anchor like so:
<a name="theanchor" />
## The HeadingThe conversion just removes the anchor. You need to insert it manually like so:
[#theanchor]
== The HeadingBogus Markdown Headers
There are 4 types of headers being used in the old pages:
Header 2
========
or
# Header 2
but this is a problem:
#[[##Header 3]]#
Yup, this is a valid Level 3 Heading.The conversion left the latter usually as = ##Header 3. More manual conversion needed.
Markdown and Velocity Templates combined
We had some .md.vtl files, which, for the most part, only used Velocity Templates to generate Admonitions. Just removing the .vtl extension, converting the file and manually cleaning up the leftover part to an appropriate Asciidoc admonition fixed this.
Conclusion
Converting sites from SCMS to JBake is certanly possible, but it takes months (depending on the size of the site).
I will post other tricks I used for jbake in upcoming articles.
You can see the staging website here: https://shiro-jbake.staged.apache.org/