Fork the repository, setup your environment, hack on the articles in your favorite text editor, commit the changes and create a pull request!
Whatever you want to contribute there are some base requirements:
- You need a GitHub account
- Either you need to fork our repository or you need commit rights on it
- You need a basic understanding how to use the common markdown syntax
- A basic understanding how Git works is useful; GitHub provides tutorials about Git repositories and GitHub as a code hosting platform
There are some concepts you should be aware of to understand how your contribution finds its way into the final product: kb
The content is written in plain text using the common markdown syntax with extensions:
- Admonition for block-styled side content (notes, tips, warnings, etc.)
- CodeHilite for syntax highlighting
- Metadata for meta data (good for accessibility and SEO)
To organize the content we use Git which is a distributed version control system (DVCS). This allows us to track each change. The main goal of Git is to support software developers in their daily business but to be pretty useful for writing documentation as well. Our credo is: "Everything as code"
Our hosting platform for this project is GitHub.
The main branch is always the state of truth. It means everything which is available in this branch goes public. Therefore, we have to handle this important branch with care. One safeguard is heavy testing (see next section). Another is we do not allow to commit changes directly into the main branch. However, what we allow is to create pull requests.
Whenever a change is submitted to our main repository this change will be tested:
- Is the used markdown syntax valid?
- Does the spell checker find any errors?
- Has the content a proper wording (avoid insensitive, inconsiderate writing)?
- Is every external link still accessible?
Our continuous integration (CI) tools try to find an answer to each above questions by running new builds. Only if each question is answered with an "yes!" the build will pass and everything is ready to merge the change.
Before anything gets published we would like to introduce our Website platform: MkDocs with the theme Material for MkDocs.
MkDocs is a static site generator. Based on the configuration it converts all markdown files to HTML and builds a Website around it. This results in a bunch of HTML pages, images, CSS style sheets and JavaScript files. There is neither any need of an application platform/a scripting language like JBoss, Python or PHP nor a running database like MariaDB in the background. This makes the Website pretty fast.
Do you like to write new articles or edit existing ones? You have two options:
- Use the built-in editor on GitHub
- Use your own editor
This is the easiest way to contribute. Additional to the basic requirements there is one more:
- You need a modern Web browser (should be no problem, right?)
Instructions depends on the operating system you are using. These are many examples which work sufficiently:
- Atom
- VIM
- Visual Studio Code (VSCode)
All listed editors can be extended to provide you an excellent writing environment.
An own environment is useful to develop on new features, fix bugs, write documentation snippets or run tests locally. This is for advanced users.
Before you start make sure all required tools are installed and configured properly:
This works on a GNU/Linux or a MacOS host:
git clone [email protected]:i-doit/knowledge-base.git
cd kb
docker-compose up -d
Our compose deployment builds and starts our knowledge-base containers based on the actual file state.
docker-compose up -d
Open http://localhost:8001 in your Web browser. You should see the home page.
Do you like to know how to write good articles? Please follow our writing guidelines.
We like you to read and follow our code of conduct before contributing. Thank you.
Have you found misspellings, grammar mistakes, logical gaps? Have not you found what you are looking for? Please report a bug in our issue tracker.
This project comes with some useful NPM scripts. List all of them:
npm run info
- If you are new to open source software read this guide: "How to Contribute to Open Source"