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 openindiana.org.
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
pacman -S git
yum install git
apt-get install git
dnf install git
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 book for quickly getting up to speed with GIT, see here: https://git-scm.com/book/en/v2
Fear not though, only basic git commands are required for working with OI-DOCS.
If your OS doesn't provide pre-packaged mkdocs, you'll need to install python-pip. This is not necessary on OpenIndiana.
pacman -S python-pip
yum install python-pip
apt-get install python-pip
|N/A - (Included with Fedora 25)
|Not needed - (Use MkDocs IPS package)
If your OS doesn't provide pre-packaged mdl, you'll need to install Ruby Gems. This is not necessary on OpenIndiana.
pacman -S ruby
yum install rubygems
apt-get install rubgems-integration
dnf install rubygems
|Not needed - (Use mdl IPS package)
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.
However, the MKDocs Material theme may need to be installed additionally using
- Most other operating systems:
pip install mkdocs-material
After MKDocs has been installed, be sure to verify your installation with
If you experience difficulties installing mkdocs, try using the python 3 version of
- For Linux Mint 18, the python 3 version of
Install Markdown Lint (mdl)
On OpenIndiana you can install mdl using standard package management tools:
pkg install developer/documentation-tool/mdl
For most operating systems:
gem install mdl -v 0.4.0
Install Markdown plugin for VIM or Emacs (optional)
Install Pandoc & XeTex (optional)
For converting the docs to PDF, OI-Docs requires a Pandoc version of 2.8 (released 2019) or above and XeTex/XeLaTex. The latest versions of Pandoc are available (in .deb & .tar.gz) from Pandoc GitHub releases. Pandoc is not yet avalible packaged on OpenIndiana.
pacman -S pandoc
yum install pandoc texlive-xetex
apt-get install pandoc texlive-xetex
dnf install pandoc texlive-xetex
|Not packaged yet
Not all OS distro repositories contain XeTex. In this case it could be installed as part of a manual TeX Live installation.
As of Summer 2021, the version of Pandoc available from OS distro repositories may be too old (was the case for Centos/RHEL and Debian < 11). In this case you can try and use the Pandoc GitHub release versions instead.
Fork the OpenIndiana Docs repository
- Open your web browser to the OpenIndiana Docs GitHub Repository.
- Click the Fork button found in the upper right hand corner of the page.
- Forking creates a server side clone of the upstream repository.
- This clone is your own personal copy of the OpenIndiana Docs repository.
Create a local clone of your fork
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
Verify things with
git remote -v
You should now see:
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).
OpenIndiana Docs site structure (master branch)
All site development occurs within the master branch.
|site root folder
|documentation root folder
|URL validation script
|PDF Generation script
|Markdown Lint configuration
|Site and menu configuration
|Pandoc configuration files folder (for makepdf.sh)
|Generated PDFs folder
|Live preview folder (no edits)
- Please do NOT perform any work within the
site/is a temporary folder created by MkDocs when the site is run locally in preview mode.
pdf/is a temporary folder for storing locally generated PDFs.
- 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.
|Legacy OpenSolaris Books
|Contributor guidance docs
|Community HCL docs
|Development oriented docs
|Site favicon icon
|OpenIndiana handbook docs
|Site front page
|OpenIndiana project graphic
|Release Notes docs
|Deprecated docs, etc.
Make some changes
Open your favorite text editor and begin authoring content.
vim somefile.md or
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:
- See the site TODO list.
- Have a look at the site Github issues list.
- See the Topics page for a list of suggestions and TODO's.
- Write a new tutorial, or complete a small section of the handbook, etc.
- Consult with other doc team contributors for even more ideas.
Adding new pages to the site menu
Site configuration settings and menus are located in
To add a page to the menu, simply add a line to this file.
See the code snippet below for examples.
- 'OpenIndiana Code of Conduct': misc/conduct.md
- 'OpenIndiana FAQ': misc/faq.md
- 'OpenIndiana Handbook': handbook/handbook.md
- OpenSolaris Books:
- 'Book Index': books/index.md
- 'Basic Administration': books/basic.md
- 'Advanced Administration': books/advanced.md
- 'Solaris Express Administration': books/express.md
- 'Trusted Extensions Administration': books/trusted.md
- 'Development Titles': books/develop.md
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.
- From the root of the
mkdocs serveand press enter.
- Open your web browser to 127.0.0.1:8000.
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
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=0.0.0.0:8000
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:
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
see “Install Markdown Lint” above.
Generating PDFs (locally)
Pandoc (via XeLaTex) is used to create PDF versions of pages.
makepdf.sh bash script automatically moves through a subset of the docs directories creating a PDF for every Markdown file.
Prior to submitting a pull request (PR), please consider running the Pandoc PDF generation script locally on your computer to ensure no Pandoc incompatibilities have been introduced.
To convert multiple pages to PDF, execute the following command from the root of the
This will produce PDF versions (placed in
oi-docs/pdf/) of most of the doc pages.
Not all pages are suitible for conversion yet, some contain incompatible HTML which needs to be fixed before they can be converted.
To convert a single file, the
-f option can be used.
-d option can be used for converting files all files in a given directory.
By default the PDFs are styled/formatted to look similar to the HTML docs produced by MkDocs.
This can be changed using the
Currently the only other option is 'opensolaris' which produces PDFs in the style of OpenSolaris Solbook documentation.
The formatting and restyling required for the PDFs is configured with files in the
pandoc/ folder of the root directory.
Each style uses a pair of files, a
.yaml file to specifiy Pandoc settings & LaTex/XeLaTex headers and a
.lua Lua script to apply formatting to the Pandoc native representation (AST).
For more information on Pandoc, see the official Pandoc Manual.
Inline HTML is not supported by Pandoc for PDF output and is not rendered at all in PDFs produced.
Ensure that you only use Markdown in your edits.
The only exception is for the mkdocs
div elements used to create these 'Note' breakouts - support for these has been manually programmed into the Pandoc lua filters.
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:
Misspelled words will now be highlighted (color varies dependent on your .Xresources file)
Keyboard shortcuts for spell checking in vim
]sto find the previously misspelled word.
[sto find the next misspelled word.
- With the cursor at the beginning of a word, use
z=to bring up a list of suggested replacements.
zgwill add a word to the local dictionary exception file.
zwis used to mark a word as incorrect.
Commit and push your changes.
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.
- Open your web browser to your forked copy of the OpenIndiana Docs repository.
- Click the button for New pull request.
- Add some notes about your change.
- Submit your PR (pull request).
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.
Created: 2016-06-11 03:01:03