New Wiki and new Wiki team member

Please welcome a new member to the Wiki team. @8Keep123. He has an extensive knowledge of everything code and will be a great asset for us. His trail blazing work with what is revealed below has been irreplaceable.

I would like to introduce to you a new way to wiki. @8keep123 and I have been working on a new site and user interface that will bring the wiki up to modern standards.

The genesis for the change is the fact that the current wiki design is hard to maintain, version and the user interface is part of the documentation repo. Not to mention, those who may take over the wiki one day, would have to figure it all out from scratch so most will not even want to try. I don’t want to waste more time on the negatives, so I will let you see what the new site looks like and describe some of the potential this design brings with it.

The site:
The demo repo for the docs:
The demo repo for the User Interface:

This uses the Antora site generator for building and maintaing documentation.

What are the benifits?

  1. Right off, the most powerful is Modularity. We can separate documentation into modules, use simver to version those modules, and the modules do not need to even be part of the wiki. Anyone can add an Antora folder structure to their own site with what’s known as an antora.yml file and nav.adoc file and the wiki can pull in that site with just a couple lines of code added to what’s known as the playbook.
  • These offsite modules can be maintained by their owners. If a particular module becomes so outdated the official wiki no longer wants it, we remove three lines of code and its gone. Nothing special needs to be done. We can maintain our own modules that relate to the jMonkeyEngine without having to maintain unrelated work. The SDK comes immediately to mind. The current wiki SDK docs could be moved to the SDK repo, a couple files later and its completely independent of the official wiki, has its own documentation and can still be a part of the wiki
  1. Antora is well documented and easy to learn. Anyone taking over the wiki will have a much easier time getting a grasp on things. Contributors will have a much easier time contributing. They aren’t even required to host their content on the wiki itself. No more wiki clutter.

  2. Another huge benefit is versioning. Antora was designed to work with repositories. So it uses what’s already there for its versioning. All we do in a playbook is add a branch value and that now is part of the wiki. So for example, the module has a master, v3.2.4 and 3.3.0 etc, we can pull any or all of those branches for a module into the wiki with a single value like so, [master, 3.3.0]. That’s it, we have a master and 3.3.0 version. Antora will only show the changes that were made when you visit that doc page, with the highest version taking precedence. If a page you visit has no changes, no other version selection option for that page will be available.

  3. Next comes docs setup. Antora uses asciidoctor for the HTML conversion, exactly as is used now. We also lose the need to set headers in the doc files as Antora has all the header attributes we currently use built right in. Give your document a title and your set. You can add an author to your page or not. Up to you. You dont have to set attributes to use macros like now, you just use them. Want an emoji, just add it emoji:smiling_imp[2x]. No header setup needed.

  4. Note that we have an overall navigation menu on the left of the UI and table of contents for any page selected on the right. The nav menu is just for demonstration right now since the wiki is not modularized yet. Once that happens, each module will have its own nav menu and we would have a better flow to it. We can add or remove modules that the team may or may not want. Another great aspect of the Antora generator is pagination. If you look at the bottom of any page selected from the menu you will see that Antora can provide links to the next and previous menu item. No more manual setting of these as links in a page and having them break if you move things around.

  5. Next comes UI separation. The UI is completely independent of the docs. It has its own repo and changes that are made there control the user interface for all modules. The templates use HTML, JavaScript and CSS language that any web developer is accustomed to already using. Big win.
    Did you notice you can change the theme? Click that toggle button in the top navbar. Pick your poison.

  6. Next, the whole build process uses GitHub workflows. The docs always pull from the UI site the latest release anytime they are built. The UI pushes new release just like is done with the engine using tags. A pushed tag will notify the docs site workflow a new UI has been released and the doc site will run its workflow, updating its UI. The whole build process for the wiki docs now would be simver based releases that can be tied to the engine release schedules.

To demonstrate the power of the playbook. If you open the window in the bottom left of the docs, you will see that there is a module that says jMonkeyEngine UI. That module is located on the jme-ui website.

If you look at the playbook, you will see it’s all of three lines to drag that module into the wiki.

If we had a version branch, it would be a simple thing to add the branch to the branches key and that version gets brought in with it, only the changes though. Just like how GitHub does things.

We await your questions and hope you all decide this should be the future for the wiki.


Congratulations, @8Keep123!
The new wiki looks awesome, keep up the great work!

Looks great!

You & @8Keep123 are the wiki team & this approach looks like it would work well into the future, so if this works for you two I don’t see any reason not to go this way.

Great work guys, this is so easy to use, I love it!

monkeys around the globe rejoice as they can now code into the night (with the new optional dark theme) without blinding themselves


@Ali_RS is also admin.


I stand corrected… if this works for the three of you I see not to forge ahead. :wink:

I wasn’t aware of it myself until today or would of brought him into this also.

Good job guys, I like new wiki especially being able to use versioning on the wiki is a cool idea.
Thanks from both of you and @david_bernard_31 as well for granting the privileges :slightly_smiling_face:


Important note: we want to have search with algolia just like the current wiki, but they told us they won’t index a test site until it’s in prod :frowning: so we weren’t able to try that yet

1 Like

To add to that, the current wiki repository site would not change, only the code used to build the current wiki changes.

1 Like

I can’t deny I’ve felt the wiki was dated every time I’ve used it. I’d say it’s a very welcome update. I hope you guys can pull it off far enough to replace the existing setup.

good work! not just more easy to use, but like you said, more easy to write/change it :slight_smile: (at least if someone know Antora)

Currently Minie’s documentation is one big markdown file. Would make sense for me to convert it over to asciidoctor and Antora?

Yes Steven. You can use asciidoc or asciidoctor syntax.

You don’t have to build a site either. All you need is the folder structure for Anotra.

Where the configured antora.yml is at the modules level with a nav.adoc file at the pages level.

The Antora docs are a quick read and well written. If you convert, we can pull the module into the wiki with zero effort. Your use case is a perfect demonstration of what makes this so powerful.

You can use node to build a site though or use the Atom editor with its built in asciidoctor and previewer, or a browser and text editor.

See the readme,

If you need something let us know.

1 Like

strive :wave:

The new wiki looks slick!

One small nit pick: Maybe the default should be ‘light mode’ since in the ‘dark mode’ the java comments are very difficult to read.

1 Like

For formal documentation it’s usually - if not always a light theme. It’s just easier to read and looks clear and concise. I agree that light mode should be default and dark mode an option.

Regarding @8Keep123 - is he going to aid you in the maintenance of the wiki or just helping you set it up? Lord knows it’s a large task for just one person.

This is the demo, default will be light.

Both, he has Maintain privileges but its always up to the person.

The real fun begins after the transition. Moving some docs into modules so that will take a little time.

Edit: There are some minor issues on dark theme still to be resolved but nothing big.

1 Like

We will let everyone know what the next steps will be after transition, we have to get together on it still.