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.
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 haven't already, sign up for a Github account.
Install and configure Git
For further details about configuring GIT, see: https://help.github.com/articles/set-up-git/
Also, if you need a good tutorial for quickly getting up to speed with GIT, see here: http://rypress.com/tutorials/git/index
Fear not though, only basic git commands are required for working with OI-DOCS.
|Fedora||N/A - (Included with Fedora 25)|
|OpenIndiana||N/A - (Use MkDocs 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
- Most other operating systems:
pip install mkdocs mkdocs-bootswatch
After MKDocs has been installed, be sure to verify your installation with
- For Linux Mint 18, the python 3 version of
Install Markdown Lint (mdl)
For most operating systems:
gem install mdl
For OpenIndiana, you will need to add the Ruby Gem directory path to your $PATH variable. To do so, execute the following commands:
PATH=$PATH:/usr/ruby/2.3/bin/ export PATH
mdl is now accessible, test using the command:
which mdl or alternately:
Install VIM Markdown plugin (optional)
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
git clone https://github.com/YOUR-USER-NAME/oi-docs.git
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 https://github.com/OpenIndiana/oi-docs.git
Verify things with
git remote -v
You should now see:
origin https://github.com/YOUR-USER-NAME/oi-docs.git (fetch) origin https://github.com/YOUR-USER-NAME/oi-docs.git (push) upstream https://github.com/OpenIndiana/oi-docs.git (fetch) upstream https://github.com/OpenIndiana/oi-docs.git (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 added 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.
oi-docs/ ├── docs/ ├── link_validator.py ├── markdownlint-rules.rb ├── mkdocs.yml ├── README.md ├── site/
|oi-docs/||site root folder|
|docs/||documentation root folder|
|link_validator.py||URL validation script|
|markdownlint-rules.rb||Markdown Lint configuration|
|mkdocs.yml||Site and menu configuration|
|site/||Live preview folder (no edits)|
- Please do NOT perform any work within the
- 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.
docs/ ├── books/ ├── contrib/ ├── dev/ ├── favicon.ico ├── handbook/ ├── index.md ├── misc/ ├── Openindiana.png └── retired/
|books/||Legacy OpenSolaris Books|
|contrib/||Contributor guidance docs|
|dev/||Development oriented docs|
|favicon.ico||Site favicon icon|
|handbook/||OpenIndiana handbook docs|
|index.md||Site front page|
|Openindiana.pgn||OpenIndiana project graphic|
|retired||Deprecated docs, etc.|
Make some changes.
Open your favorite text editor and begin authoring content.
Some text editors (Atom, VIM, etc.) natively include Markdown syntax highlighting (or offer it as a plugin).
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.
- Docs: - '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
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:
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 add the path to your
On OpenIndiana, markdown lint (mdl) resides in
/usr/ruby/1.9/bin/ which is not normally part of the search path.
To run this command without having to specify the complete path each time, add the following to your
PATH=$PATH:/usr/ruby/1.9/bin/ export PATH
To immediately effect this change, source your
.bashrc as follows:
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.
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 your local 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.
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.