Initial Skills
Get started by setting up your development environment and contributing to the Zillona Org documentation project.
Install Debian VM
Install Necessary Packages
- mkdocs
- git
- docker
- vim
Contribute to the Documentation Project
Zillona Org documentation is publicly viewable at https://zillonaorg.github.io or https://docs.zillona.org
The HTML is hosted via GitHub from the publishing repository at github.com/zillonaorg/zillonaorg.github.io
Pull the Documentation Source Repository
The Markdown source for the documentation project can be found at github.com/zillonaorg/Welcome
To contribute to the documentation project pull the source repository, change directory into the local git clone and create a new branch from the "develop" branch.
git clone https://github.com/zillonaorg/Welcome.git
cd ./Welcome/
git checkout develop
git pull
git checkout -b YOUR_BRANCH_NAME
Edit the Markdown Files with Your Changes
Open another shell/terminal and change directory into your local git clone again. From the root of your local repo where you find the mkdocs.yml file, run the MkDocs server to render your Markdown files as HTML locally.
cd Welcome
mkdocs serve
You may have to prepend your mkdocs command with python -m as follows
python -m mkdocks serve
The MkDocs server will continue to run in the foreground of the terminal outputting logs as you make your changes. Return to your other terminal to continue with your local development.
While the server is running you can view your changes, rendered as HTML code in real time by visiting http://localhost:8000/ in your browser.
Please reference this cheat sheet from makeareadme.com and the official GitHub Markdown style guide when editing the Markdown files.
Share Your Changes
To contribute back to the documentation project and share your changes you will need to use git commands to add, commit and push your local changes back to GitHub.
git add CHANGED_FILE_NAME
git commit
git push --set-upstream origin YOUR_BRANCH_NAME
Create a Pull Request
Merge your branch back into the develop branch.
Publish Your Changes Publicly
Once your changes along with all other changes to the develop branch have been validated a pull request against the main branch will be created to deploy a "release" of the public documentation website.
Once the develop branch has been merged to main we can create the HTML website from the main branch using MkDocs.
Once again the mkdocs command must be ran from the root of your git repository.
mkdocs build -s
Again, you may have to prepend your mkdocs command with python -m as follows
python -m mkdocks build -s
MkDocs will convert the Markdown files inside the /docs directory into an MkDocs HTML website stored in a new /site directory created by the build process.
The resulting website "artifact" is ready for deployment to any webserver. We host our documentation website in GitHub at https://zillonaorg.github.io.
Deployment is achieved by pushing the website artifact changes to github.com/zillonaorg/zillonaorg.github.io and merging to the main branch.