Contributing to the Wiki is now easier than it ever has been. Using the Atom editor will give you an easy to use interface that is cross-platform, has code completion, syntax highlighting, instant AsciiDoctor page previewing, with an integrated GitHub client. The only thing it doesn’t do is write the page for you.

Atom Editor Setup

  1. Download and install the Atom editor - https://atom.io/

  2. After installation is complete, you can customize the editor by selecting the Choose A Theme panel followed by the Theme Picker button.

  3. Once you are satisfied with the customization of the editor, you will need to add several packages to make Atom AsciiDoctor compatible. Package installation is painless.

    • From the Install A Package panel, select the Open Installer button, or select Packages ▸ Settings View ▸ Install Packages/Themes from the file header.

    • Enter “asciidoc” in the search box and press the Packages button.

    • Add these packages:

      language-asciidoc
      asciidoc-preview
      autocomplete-asciidoc

  4. To edit the Wiki you will need to clone the wiki repository.

    • From the Command Palette (ctrl+shift +P or Packages ▸ Command Palette ▸ Toggle), enter “git” into the search box.

    • Select GitHub: Clone.

    • Paste https://github.com/jMonkeyEngine/wiki into the Clone from box. The To directory will automatically update when you do.

    • When you’re ready, press the Clone button.

      The clone will take some time due to the size of the Wiki. Once cloned, a new Project tab will open on the left, and the Git and GitHub Preview tabs will open to the right. If they don’t, you can open the Git tab using ctrl+shift+9 and the GitHub Preview tab using ctrl+shift+8. Alternatively, you can navigate the Packages ▸ GitHub menu. You will also notice in the lower right corner, on the Status Bar, you now have your GitHub control.

All Wiki documents live in the asciidoc folder, images in the images folder, and resources for your documents in the resources folder. Select an appropriate folder under each to store your new document, image or resource.

Before you can commit any changes to the Wiki, you must configure at least the user.email and user.name variables for Git. You can do this via Git Bash, or manually, by following these instructions.

  • Setting your commit email address in Git

  • Manually - Open your .gitconfig file and add,

    [user]
        name = yourname
        email = youremail

    To maintain your privacy, setup your email settings in your GitHub account and use the users.noreply.github.com email address.

Lastly, you will need to create a GitHub token. Follow the directions in the popup to enter the token.

When you edit a Wiki page, the Git tab will show any unstaged changes. When you’re done making changes, you stage any or all changes, write your commit message, commit, and then push the changes.

You can add more GitHub controls to the editor by adding the package git-plus.

You can preview your documents by selecting the document and using the keyboard shortcut ctrl+shift+A or by using the File header menu Packages ▸ AsciiDoc Preview ▸ Toggle Preview.

Wiki Template

To make things even easier, you can create your own Wiki template for page creation. You must first have the file-templates package installed. You can find this package by selecting File ▸ Settings ▸ Install and typing “template” into the search box.

  • Once installed, from the Command Palette (ctrl+shift +P or Packages ▸ Command Palette ▸ Toggle) enter “file” into the search box.

  • Select File Templates: New Template.

  • For Template Name, use Jme3 Wiki Template, and when ready select Create.

  • From the Command Palette, enter “file” and select File Templates: Update Template.

  • If this is the first template it will open automatically. If not, then select the Jme3 Wiki Template you just created and press the Edit Template button.

  • Copy and paste the text below into the head of the document.

    = Enter Document Title Here
:author: @author@
:revnumber:
:revdate: @timestamp@
:relfileprefix: Enter path to asciidoc folder ../../
:imagesdir: Enter path to images folder ../..
:experimental:
ifdef::env-github,env-browser[:outfilesuffix: .adoc]

  • When done, close the document and when it asks you if you want to save it select Yes .

You can now use your template when creating new Wiki documents by opening the Command Palette, entering “file” into the search box, and selecting File Templates: New File.

To edit the template, from the Command Palette (ctrl+shift +P) type “file” into the search box and select:
File Templates: Update Template → Jme3 Wiki Page → Edit Template

Save the edit when finished.

See also:

Anatomy of a Wiki Header

Atom Snippets

Snippets are an incredibly powerful way to quickly generate commonly needed code syntax from a shortcut.
— Atom Flight Manual: Snippets

One advantage of using Atom as an editor for the Wiki comes from the use of Snippets. You can see a list of available snippets for your document by using the Command Palette (ctrl+shift +P or Packages ▸ Command Palette ▸ Toggle). Enter “snippets” into the search box and select Snippets: Available.

The Atom AsciiDoc packages add great functionality to the editor, but they do not cover everything that’s possible when using AsciiDoctor syntax. You can customize the editor even further by adding your own snippets. I will get you started with your first snippet. Simply copy and paste the code below into your “snippets.cson” file and save. You can locate the file under File ▸ Snippets.

'.source.asciidoc':
  'Inter-Doc Cross Reference':
    'prefix': 'xref'
    'body': '<<${1:path/to/wiki/page}#,${2:custom label text}>>'

Thereafter just type xref and hit Tab to insert an Inter-Document Cross Reference link. You can then use the Tab key to cycle through each tab stop when your ready.

You can help the jMonkey community by adding new snippets. Use your editor and edit the Atom Snippets document. Make sure to announce any proposed changes on the jMonkeyEngine Forum under the topic “Documentation” first so others are aware and can test out your proposed change.

Next steps,