THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Static Site Generation/Build Tools
Reasoning
Why would we want a site generation/build tool versus statically maintaining a site? Branding and time. Imagine we had to edit X number of files to replace a footer or header versus editing a single file. What if we had to edit X pages just to replace the site logo? This would be horribly time consuming, and as we grow here at Apache, will become great overhead impacting accuracy and possibly releases.
Other Apache projects use build tools. The Groovy project built their own some time ago. There are static site tool projects which use other Apache projects such as Groovy and FreeMarker with JBake being such an example, and hopefully one of these will work for our needs, to promote the Apache tools, and can be the first attempt at a successful static site generation project for NetBeans.
There are also other tools which use Ruby, Python, or Node JS. Various tools have been reviewed, and do quite similar things. If a Java tool such as JBake which uses or allows the use of different Apache projects can not be used, then perhaps one of those can be used, and in that case we should consider a Node JS build tool as the browser front end market and developers have been using Node JS stacks more frequently, and perhaps would be closer to the problem in this case, and NetBeans has great support for Node JS projects.
Possible and Reviewed Static Site Generators
As mentioned in the reasoning, there were various reviewed tools built on different stacks such as Java, Ruby, Node JS, and Python. In the process of this work, rolling our own generator was not considered, but could certainly be considered and reviewed, as the Groovy project did this as an example. All reviewed tools market themselves as Static Site Generators, and was the main criterion used to determine if a project should be reviewed, along with having an Apache approved OSS license.
Criterion included (weighted by order)
- Does the project consider itself a static site generator or advertise it could, versus mainly just blogs, and without rolling our own
- Does it support transferring the current site content with less effort; not too much manual changing, or could be fairly trivial transformed using scripting such as Groovy and JSoup to convert current HTML into content HTML less Markdown, AsciiDoc, or other
- Does it support HTML content (necessarily different than templates); goes with 2 above
- Does it support common web and document formats, standards, and idioms
- If the tool had deficits in the above, how easy would it be to integrate with common Java build tooling to fill the gaps
- Simplicity of use; perceived
- Would the tool be familiar to NB project maintainers (the Java ecosystem, or at least close enough if not enough tools could be found such as tooling supported by the IDE)
- What template engines it supported out of the box or with supported plugins (those in the Apache ecosphere were rated higher), and ease of use
There are certainly others, but the following is a good sampling of some of the top ones from their given categories.
JBake (Java based)
Java seems to have a quite limited SSG market, and thus far, without rolling ones own with Groovy, JBake seems the best. It also uses various Apache projects or ones licensed with the Apache license. It may not necessarily be the best SSG out there, as Jekyll, Metalsmith, and Nikola have a lot of features, and seem quite robust. However, it does accept html content input, allows Java developers to use Java ecosystem templates such as Thymeleaf, Groovy, and Freemarker, and seems to integrate nicely with Gradle which allows some of its limitations to be easily overcome by adding some extra preprocessing by way of other Gradle plugins and tasks such as SASS processing.
HTML as content input out of the box is fairly important as it hopefully allows those working on site transition from netbeans.org to a static version to do less rewriting from .html files to .md (or other). This was listed in the criteria.
JBake also seems quite simple to work with, and is fairly trivial to get setup with a basic site. One aspect which is missing, and could be subjective, is the ability to have JavaScript dependencies annotated and downloaded from the tooling. That said, this can be combined with a Node JS sub-project which could be driven with Gradle and a plugin. This same method could be used for minification and other JS tooling. This similar to the SASS plugin mentioned before.
Jekyll (Ruby based)
Jekyll is a highly popular SSG. It is well documented, and supports quite a lot of features out of the box. It does have some specific structure specifics enforced on the project and content however. It also seems quite a large project with much documentation which can be a catch 22 for this problem at the start, but may be something to look at once we have some initial SSG in place. One issue with Jekyll is the use of Liquid. Groovy, Thymeleaf, and Freemarker templates can do some really nice logic if we need it, and Jekyll is meant to be a secure environment for Github pages. At first, it appeared to not support .html files in structured content, but after another review per some dev list comments, that does seem possible.
Metalsmith (Node JS)
Metalsmith is a quite simple Node JS which like gulp uses a streamed build approach. There are various plugins one can include in their build file which them supports various formats. The HTML input for content was not yet found, but may exist. This seemed to expose an issue with the documentation not being organized well. The project itself seems to support quite a lot of functionality including layouts and tools which front end developers find useful. This would be another tool to look at once we have something in place. It seems it may take more time to get up to speed on it, but Metalsmith looks like it could be promising.
Wintersmith (Node JS)
Wintersmith seems like it could be a good tool, but its documentation is quite lacking, or possibly just organized badly. It does seem to have a hearty plugin system to support a lot of what one would want to do, but I did not find quickly that HTML content can be used easily outside of templates/layout processing. It could be worth another look in the future, but Metalsmith seems further along.
Hyde (Python)
Hyde is an interesting project in that it is said to be Jekyll's evil twin. That said, the documentation was quite lacking, contrasted to the great docs of Jekyll. Too, if it is the evil twin of Jekyll, then one can assume it supports quite a lot of functionality undocumented, but this could be a guess. It also uses some nonintuitive notions of "media" as it assumes CSS and JS would naturally fall under the same asset concept where as this may not be accurate at all, and thus seems to force this nonintuitive structure on projects.
Nikola (Python)
Nikola would probably be better described as Jekyll's evil twin in the Python world versus Hyde as it is robust and well documented. It also seems to impose less limitations on structure, and is highly configurable. It also supports HTML content input like JBake out of the box which is important per the current criteria. Nikola is certainly an option for the future.
Current SSG Suggestion
The current suggestion is JBake along with Gradle to fill in any gaps. Gradle can initially provide SASS preprocessing capabilities along with any others as mentioned in the section on JBake above. JBake also supports less changes to the current NB site structure while allowing us to rebrand the site as it allows a flexible structure and HTML content. We will need to write some scripts to perform some content preprocessing as JBake supports HTML fragments in .html files for content, but this should be fairly trivial with Groovy and JSoup, and would be necessary regardless of the chosen SSG. Patterns are being identified which can be baked into such scripts. Then, JBake can be used to merge the new site look and feel with the old site structure as much as possible.
It is suggested future articles, posts, and content, beyond the initial migration, use Markdown as the editing language choice as it is certainly easier to type and edit, and the templates and engine will handle the content layout along with transforming Markdown to HTML for the site fitting the templates. This gives a good starting or conversion point plus a better editing experience for the future.
Possible Future SSG Suggestions
Per the SSGs reviewed it seems Nikola or Metalsmith would probably be good evolutions if JBake and Gradle can not keep up with where the projects needs travel, and with a little more time with those tools, they seem likely to be successful. Jekyll may also be a good option, but it would depend on its allowed structures, but it certainly has many plugins and tools which front end developers find useful, but one must use Liquid for its templates, and only Liquid, but Nikola supports HTML content out of the box, and Metalsmith may be able to support such a notion going forward or already by way of a plugin along with many tools front end developers find useful.
Envisioned Generated Site Layout
As much of the current NB site directory structure layout should be used as possible. This means things such as https://netbeans.org/kb/index.html and https://netbeans.org/kb/trails/java-se.html will continue to work if folks have permalinked them. However, assets and media should be rearranged. Currently CSS and JS are scattered in nonintuitive places such as under /images_www, and the CSS is under various directories. This should be better organized into either a top down layout such as:
/images
/css
/js
or
/images
/assets
/css
/js
Or, the site should be organized more along the lines of web components. At the moment, the current site seems a mild hodgepodge albeit those more web component type things reside under sub-structures in /images_www, and could still be considered more top down. For the sake of getting the site over to Apache, it is suggested a top down approach matching either of the above can be fine, and either will require the same amount of effort for scripted replacements of the current content to get it into the needed SSG structure.
The current site structure follows the below, less the asset changes mentioned above:
TBD
New Site Plan
Converting the existing site to JBake will require a Gradle build setup, JBake configuration, a project structure, templates and layout, choices between page types and site sections, and some scripts to modify the current "content" files to match what JBake needs. This section will layout what that is. The output of these scripts, builds, templates, and content should deliver the envisioned generated site layout. This is obviously just a starting point at this time to be tweaked with other community members, but gets the SSG in place, to then be styled and beautified as needed.
TBD