Contributor Tools
Introduction
The OpenIndiana Docs website uses 2 principal technologies and several ancillary technologies:
Principal technologies:
- The MkDocs content authoring framework.
- The Markdown text markup language.
Both technologies leverage the Python programming language.
Ancillary technologies:
- GitHub - Git repository hosting
- GitHub Pages - Website publishing from a GitHub repository
- GitHub Actions - Continuous Integration toolset
- Git - Distributed version control
Why use Git distributed version control for docs?
- Integrity - You can roll back to previous versions
- Mobility - You can edit docs anywhere, no Internet connection required
- Consistency - Docs are treated just like code
Why a text markup based docs framework?
The primary advantage of using a text markup language is:
- Readability
- Flexibility
The raw code for your authored content is simple plain text. No need for special tools such as WYSIWYG XML editors, etc.
What is MkDocs?
MkDocs is a modern, flexible, and feature rich content authoring framework and static website generator. The python based MkDocs framework publishes content as HTML5. In conjunction with the MkDocs-Pandoc module, content may also be published in the PDF and EPUB formats.
Unlike a CMS system where you are restricted to the confines of an integral editor, the OpenIndiana Docs website has no such restriction. Here content is authored using a simple text based markup. Because you are working with plain text files, content may be authored using Atom, EMACS, Gedit, Nano, VIM, or any other text editor. The choice is yours; Use your favorite editor.
MkDocs system characteristics
- Easy to use Markdown syntax.
- Produces professional quality output.
- Extensible - accepts plugins.
MkDocs and Markdown informational links
| URL | Description |
|---|---|
| http://www.mkdocs.org/ | MkDocs Content Authoring Framework |
| https://python-markdown.github.io/ | Python implementation of Markdown |
| http://spec.commonmark.org/0.25/ | The CommonMark Markdown Spec |
| https://github.com/mivok/markdownlint | Markdown Lint |
| https://pages.github.com/ | Publish from your github repo |
The OpenIndiana Docs GitHub repository
The OpenIndiana Docs repository: https://github.com/OpenIndiana/oi-docs consists of 2 branches:
- master
- gh-pages
Development occurs in the master branch. The gh-pages branch is used to publish the site to GitHub pages.
Docs site publishing
Following the best practices of continuous integration, the OpenIndiana Docs website is fully automated using GitHub Actions. Upon a pull request or commit to the site GitHub repository, GitHub Actions immediately performs a series of validation tests. If the validation tests pass, then the website is automatically published to Github Pages.