You are welcome to add your additions and improvements to the documentation directly to the repository. For this, you’ll need a GitHub account and a little knowledge on git:
All documentation is written in markdown. Behind the scenes we use GitHub Pages to automatically publish the documentation. GitHub Pages in turn uses Jekyll to render the pages. Below are some useful links to documentations on all these techniques and systems:
However, don’t worry to much about all this new information. You’ll see that markdown is quit intuitive. Besides, we will check your changes too. If you find it all too overwhelming anyway, or if you just don’t feel like going through all this hussle, you are always free to just send us an e-mail with your remarks and we will change the documentation ourselves: email@example.com
Please consult the following guidelines before contributing updates, bug fixes, or other corrections.
This section is still under construction. As we need your feedback to keep improving the documentation, we encourange you to send your remarks at firstname.lastname@example.org.
Highlight important text in bold letters. Have a look at the source and notice the double asterisks wrapping the emphasised text.
We want to distinguish
OpenNebula keywords, such as
Virtual Machine or
Template. Have a look at the source and notice the accents wrapping the keywords.
We want to emphasise user interface menu items, such as Sign Out. Have a look at the source and notice the underscore wrapping the keyword.
Callouts and text blocks of high attention should be different to body text.
Here is an example.
VMs are created by instantiating a
Have a look at the source and notice the character
We want command lines without leading prompt, so that the user may tripple-click and copy/paste it.
To stimulate non-root access, prefix with
sudo if needed.
Output should be visually different from the command by block-quoting it.
Here is an example.
Please execute the following command:
sudo rm -rf * .o
rm: .o: No such file or directory
Have a look at the source and notice the blank line between
Expected output: and the
This seems to be the only way to have different editors and renderers to create the same output.
You can create a new page, by creating a new markdown file. The file should have .markdown as extension, because else the ‘Edit on GitHub’ button will not function.
Start the file with the name of the template you want to use. Available templates can be seen in the _layouts directory. You can use the filename, without the extension. For example:
--- layout: default ---
After these three lines, you can add regular markdown. You can link to the new file by using the filename without the extension.
Before committing anything, you can first have a look at your changes using Jekyll. You can install Jekyll normally (see link to Jekyll website at the top of this page), or use docker for this. From the root of this repository, run:
sudo docker run --detach --name=jekyll --label=jekyll --volume=$(pwd):/srv/jekyll -t jekyll/jekyll:pages jekyll s sudo docker inspect jekyll | grep '"IPAddress"' | sed -re 's|[[:space:]]*"IPAddress": "([^"]+)",|View your documentation at http://\1|'
This will start the Docker container in the background and show you the address where you can view your documentation. This is basically through HTTP access on port 4000 of the IP address of your container.
Please, also have a look at the Docker documentation for more information on Docker.
Please add more best practices here.