jMonkeyEngine-wiki/docs-transition/modules/ROOT/assets/attachments/README.adoc

= jMonkeyEngine Documentation

image:https://github.com/jMonkeyEngine/wiki/workflows/Build%20Docs/badge.svg[Status Badge, 175, 25]

see link:https://wiki.jmonkeyengine.org/docs/[https://github.com/jMonkeyEngine/wiki]

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

The documentation `docs/modules/ROOT/pages` is editable :

* Online via github (Edit link located on the top navbar of the Wiki + Pull Request)
* Offline with the Atom editor, which includes a built in previewer and code editor. see link:https://wiki.jmonkeyengine.org/docs/wiki/atom_editor.html[Atom Editor for Wiki Editing],
* Any text editor and browser program of your choice.
* Setting up your own local Node.js environment.

.Prerequisites
.  Have a link:https://github.com/[GitHub account].
.  Optional: Are a Wiki project member.

If you are not a member, you can fork the repository into your GitHub account and issue pull requests via github.

To fork the Wiki repository into your GitHub Account:

*  In the menu at the top of the docs.jmonkeyengine.org page, select the *Fork* button.

The syntax is asciidoctor:

*  link:http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoc Syntax Quick Reference]
*  link:http://asciidoctor.org/docs/user-manual/[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.

. It's not required but it's a good idea to give a heads up you made a P/R on the link:https://hub.jmonkeyengine.org/[jMonkeyEngine Forum] under the `Documentation` topic.
.  When adding documents, make sure to always complete the header of your document first.
** see link:https://wiki.jmonkeyengine.org/docs/wiki/wiki_header.html[Anatomy of a Wiki Header]
.  The docs are modular so you can create your own Antora site playbook and module and it can be included in the wiki and maintained by you. see link:https://docs.antora.org/antora/2.3/[Antora Docs].
. You can create modules and submit them here also.
.  When linking to other Wiki pages located in the `ROOT` module, 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 `pages` folder.

For example: `++<<jme3/requirements#,Software and hardware requirements>>++` +
links to the `requirements.adoc` page, which lives in a sub-folder of `pages` 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.
--
. See link:https://docs.antora.org/antora/2.3/navigation/[Antora Navigation] for creating nav menues and navigation between modules.
.  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.
. When linking to the jMonkeyEngine javadocs, use the global attribute `pass:[{link-javadoc}]` in your link path.
+
.Link example
```
link:{link-javadoc}/com/jme3/app/state/BaseAppState.html[BaseAppState]
```
** see link:https://wiki.jmonkeyengine.org/docs/wiki/wiki_header.html[Anatomy of a Wiki Header] for details on how to override this setting.

== Build & Preview

To set up the Antora environment, you'll need Nodejs (tested with node 12).

From your local wiki directory.

Run:
```
npm install
npm run buildDocs
```

This will install the needed dependencies and run the static site generator. The documentation will be output to the directory `build/site`.

To preview, navigate to the `build/site` directory and open the index.html file in your browser.

see: https://docs.antora.org/antora/2.3/preview-site/