Getting Started with OpenIndiana Docs

The process for contributing to OpenIndiana Docs is simple and follows the same best practices used in the development of the OpenIndiana distribution.


First and foremost, we understand using development tools and techniques to write end user documentation is not for everyone. For this reason, we're happy to accept your contribution in any format you wish to provide.

After receiving your submission, we will review the document for conversion to markdown and subsequent incorporation into OpenIndiana Docs. Contributions may be submitted in plain text, .doc, .docx, .odt, html, xml, latex, pdf, GitHub Gist, etc.

In summary, if you believe your contribution would be helpful to the greater OpenIndiana community, we'll be willing to review it. For further information, please contact us via one of the methods provided below.

To make a suggestion or report a problem with a document, please make your request by submitting a Github issue.

The docs team can be reached via email: docs at

You may also inquire via IRC:


If you would like to make a contribution using the development tools, you must have a GitHub account. If you do not already have a GitHub account, sign up for a Github account.

Install and configure Git

Operating System Command
Arch pacman -S git
Centos/RHEL yum install git
Debian/Mint/Ubuntu apt-get install git
Fedora dnf install git
OpenIndiana pkg install git


After GIT is installed, be sure to configure your name and email address.

For further details about configuring GIT, see:

Also, if you need a good tutorial for quickly getting up to speed with GIT, see here:

Fear not though, only basic git commands are required for working with OI-DOCS.

Install python-pip

If your OS doesn't provide pre-packaged mkdocs, you'll need to install python-pip. This is not necessary on OpenIndiana.

Operating System Command
Arch pacman -S python-pip
Centos/RHEL yum install python-pip
Debian/Mint/Ubuntu apt-get install python-pip
Fedora N/A - (Included with Fedora 25)
OpenIndiana Not needed - (Use MkDocs IPS package)

Install rubygems

If your OS doesn't provide pre-packaged mdl, you'll need to install Ruby Gems. This is not necessary on OpenIndiana.

Operating System Command
Arch pacman -S ruby
Centos/RHEL yum install rubygems
Debian/Mint/Ubuntu apt-get install rubgems-integration
Fedora dnf install rubygems
OpenIndiana Not needed - (Use mdl IPS package)

Install mkdocs

For OpenIndiana Hipster, MKDocs and all of it's dependencies have been packaged and are available in the OI Hipster repository. So, if you're already running Hipster, installing MKDocs is as simple as: pkg install mkdocs

After MKDocs has been installed, be sure to verify your installation with mkdocs --version


If you experience difficulties installing mkdocs, try using the python 3 version of pip.

For example:

  • For Linux Mint 18, the python 3 version of pip would be pip3.

Install Markdown Lint (mdl)

On OpenIndiana you can install mdl using standard package management tools:

For most operating systems:

Install Markdown plugin for VIM or Emacs(optional)

Fork the OpenIndiana Docs repository

Create a local clone of your fork

git clone

The local clone is where you will perform your work. Think of your local clone as your working copy of the repository. The local clone is also where you will commit your changes. Periodically you will push these local changes to your fork residing on Github.

Add the upstream repository

cd oi-docs
git remote add upstream

Verify things with git remote -v

You should now see:

origin (fetch)
origin (push)
upstream (fetch)
upstream (push)

Sync and merge changes from the upstream repository

Periodically you will want to rebase your local copy by bringing in changes from the upstream repository. In plain English, this means the upstream repository is locally registered so you can periodically pull down changes from the upstream master repository and merge them into your local clone. This way your local clone remains in synchronization with the master upstream repository. It is always a good idea to perform a pull from the upstream master repository prior to making changes to your local clone (working copy).

git pull upstream master

OpenIndiana Docs site structure (master branch)

All site development occurs within the master branch.

├── docs/
├── markdownlint-rules.rb
├── mkdocs.yml
├── site/
Resource Description
oi-docs/ site root folder
docs/ documentation root folder URL validation script
markdownlint-rules.rb Markdown Lint configuration
mkdocs.yml Site and menu configuration Git readme
site/ Live preview folder (no edits)


  • Please do NOT perform any work within the site/ folder.
    • This is a temporary folder created by MkDocs when the site is run locally in preview mode.
  • Also, please do NOT perform any work within the gh-pages branch.
    • The gh-branch is destroyed and rebuilt each time the site is deployed to GitHub pages.
├── books/
├── contrib/
├── dev/
├── favicon.ico
├── handbook/
├── misc/
├── Openindiana.png
└── retired/
Resource Description
books/ Legacy OpenSolaris Books
contrib/ Contributor guidance docs
dev/ Development oriented docs
favicon.ico Site favicon icon
handbook/ OpenIndiana handbook docs Site front page
misc/ Miscellaneous docs
Openindiana.pgn OpenIndiana project graphic
retired Deprecated docs, etc.

Make some changes

Open your favorite text editor and begin authoring content.

For example: vim or emacs

Some text editors (Atom, VIM, etc.) natively include Markdown syntax highlighting (or offer it as a plugin).


Major changes should be performed within a separate branch, appropriately named to reflect the changes being made.

For a list of subject to write about:

Adding new pages to the site menu

Site configuration settings and menus are located in mkdocs.yml. To add a page to the menu, simply add a line to this file. See the code snippet below for examples.

- Docs:
        - 'OpenIndiana Code of Conduct': misc/
        - 'OpenIndiana FAQ': misc/
        - 'OpenIndiana Handbook': handbook/
        - OpenSolaris Books:
                - 'Book Index': books/
                - 'Basic Administration': books/
                - 'Advanced Administration': books/
                - 'Solaris Express Administration': books/
                - 'Trusted Extensions Administration': books/
                - 'Development Titles': books/

Visualize your changes using live preview

To assist with the content authoring process, it may be helpful to visualize your changes using a live preview.

Each time you save your changes, the site page is automatically reloaded within your web browser.

To shut down the live preview web server, use CTRL + C.


If you wish to preview your changes on a remotely networked system or on a networked mobile device such as a tablet, the site can also be served on your LAN IP address.

To do so, issue the following command: mkdocs serve --dev-addr=

Running Markdown Lint (locally)

Markdown Lint is used to check your changes for Markdown syntax errors. Prior to submitting a pull request (PR), please consider running Markdown Lint locally on your computer.

From the root of the oi-docs/ directory, execute the following command:

mdl -s markdownlint-rules.rb .

Markdown Lint will automatically traverse the entire folder structure looking for problems. Alternately you may also run mdl on a specific file. Simply replace the period (.) with the path to the file.


Before you can run mdl, it may be necessary to modify your $PATH variable: see “Install Markdown Lint” above.

Enabling spell checking in vim

You can invoke spell checking in your current session by inputting the command:

:set spell spelllang=en_us

If you would like a more permanent solution, enable spell checking in your .vimrc by adding the line:

set spelllang=en_us

Misspelled words will now be highlighted (color varies dependent on your .Xresources file)

Keyboard shortcuts for spell checking in vim

Commit and push your changes.

git status
git add some-file-you-just-edited
git commit -m 'your commit message'
git push

When you make a commit, you are committing those changes locally to your clone. When you perform a push, your are pushing your commits from your local clone to your fork residing on Github.

Send a pull request.

For example:

Pull requests are used to request a pull in of changes from your fork to the master repository.


After a pull request has been submitted, and for the duration of time your pull request remains open and uncommitted to the OI-DOCS master repository, any additional commits you make to your own fork of the oi-docs repository will automatically be included in your open pull request.

What happens next?

At this point a member of the OpenIndiana Project docs team will review your changes. If no corrections are required, your changes will be accepted and merged into the upstream repository.

Upon commit, publishing occurs automatically using Travis-CI.