jMonkeyEngine-wiki/README.adoc

:experimental:

image:https://travis-ci.org/jMonkeyEngine/wiki.svg?branch=master["Build Status", link="https://travis-ci.org/jMonkeyEngine/wiki"]

= jMonkeyEngine Documentation

see http://jmonkeyengine.github.io/wiki/documentation

The project to store, edit, and generate the documentation of http://jmonkeyengine.org[jMonkeyEngine].

The documentation (<<src/docs/asciidoc>>) is editable :

* online via github (Edit button located at top of the Wiki page + Pull Request)
* offline with Netbeans after local `git clone` + open
* offline with Atom editor, see link:https://jmonkeyengine.github.io/wiki/wiki/atom_editor.html[Atom Editor for Wiki Editing]

The syntax is asciidoc :

*  link:http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoc Syntax Quick Reference]
*  link:http://asciidoctor.org/docs/user-manual/#introduction-to-asciidoctor[Asciidoctor User Manual]

An easy to use primer for GitHub commands can be found here:

*  link:http://rogerdudler.github.io/git-guide/[git - the simple guide]


== Contribute

There are a few simple rules to follow when contributing.

.  When adding documents, make sure to always complete the header of your document first.
** see link:https://jmonkeyengine.github.io/wiki/wiki/wiki_header.html[Anatomy of a Wiki Header]
.  When linking to other Wiki pages, always use an "`Inter-Document Cross Reference`" with the format,
** ++<<path/to/wiki/page#,custom label text>>++ +
The `#` sign substitutes for the file extension. This type of link will first look for the `.adoc` file and if not found default to the `.html` version.
+
The path should be relative to the `asciidoc` folder.
+
For example: `++<<jme3/requirements#,Software and hardware requirements>>++` +
links to the `requirements.adoc` page, which lives in a sub-folder of `asciidoc` named `jme3`.
+
See link:http://asciidoctor.org/docs/user-manual/#inter-document-cross-references[http://asciidoctor.org/docs/user-manual/#inter-document-cross-references] for more info.
.  When linking to images stored in the wiki repository, always use an image prefix in front of the file name and square brackets after it with the format,
**  Image on its own line  - `image::path/to/image.jpg[image alt text,width=" ",height=" ", align=" "]`
+
For example: `++image::jme3/beginner/beginner-assets-models.png[beginner-assets-models.png,320,250,align="center"]++`
+
*  This image is on its own line.
*  Is stored in the `jme3/beginner` folder which lives in the `images` folder.
*  Is named `beginner-assets-models.png`.
*  Has a `alt text` name of `beginner-assets-models.png`.
*  Has a width of 320.
*  Has a height of 250.
*  Is aligned in the center of the page.
**  If you want to include an image inline, use the `image:` prefix instead (notice there is only one colon):
+
See link:http://asciidoctor.org/docs/user-manual/#images[http://asciidoctor.org/docs/user-manual/#images] for in depth instructions.


== Build

*  In Netbeans, convert the AsciiDoc to HTML5 by invoking the 'asciidoctor' goal:
+
[source]
----
 $ ./gradlew asciidoctor
----
+
Open the file _build/asciidoc/html5/index.html_  in your browser to see the generated HTML file.

*  In Atom, you see real time changes when using the `AsciiDoc Preview` (kbd:[ctrl]+kbd:[shift]+kbd:[A] or `menu:Packages[AsciiDoc Preview>Toggle Preview]`). No build is required.

== TODO

- [x] configure travis build
- [x] configure github + gradle + travis to publish on gh-pages branches
- [x] find and fixe conversion bug
- [x] complete conversion: note, warning, ...
- [ ] fix warning during html's generation (should be fixed manually)
- [x] add meta info during conversion (doctitle, revision, tags, ...)
- [x] add a home page (index.html)
- [ ] add a navigation bar or a menu (?)
- [ ] customize html layout (header, footer, css)
- [x] transfer ownership to jMonkeyEngine org
- [x] complete Doc, how to contribute,...
- [ ] accept Pull Request
- [ ] write a post about the migration (the tools, why asciidoc, vs alternatives, how ...)
- [ ] generate sitemap
- [x] add search box
- [ ] add google analytics (?)
- [ ] support emoji
- [ ] support iframe block
- [ ] fix slideshow of "Xxx for Dummies"
- [ ] optimize remove useless images
- [ ] optimize image, use smaller file, eg convert to jpg or to webp, resize
- [ ] organize i18n / lang
- [ ] use tags to create taxonomy