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: docs
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.
To deploy from the main branch to production we also use Jenkins to do this job. In this step Jenkins acts as a continuous deployment (CD) tool. The final result (remember: a bunch of HTML/images/CSS/JS) will be transferred to our production environment and is live immediately.
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:
- Git
- Python 3 (2 does not work) with PIP
- GCC to compile some required Python packages
- NPM, version
>= 6.7.0 - Node.js, version
>= 14.16.0
This works on a GNU/Linux or a MacOS host:
git clone git@github.com:docupike/docs.git
cd docs
npm install
pip install -U -r requirements.txt
MkDocs has a built-in Web server which keeps track of your changes. Whenever you add a new file or update an existing one your Web browser reloads the current page automatically. Start the Web server:
npm run docs:serve
Open http://localhost:8000 in your Web browser. You should see the home page.
Build the static website:
npm run docs:build
The result will be located within the site/ directory.
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
- If you are new to open source software read this guide: "How to Contribute to Open Source"