How to use this website
Search
This is a custom Google search engine covering the www.machinekit.io website and the blog.
Editing pages
The site source is hosted on github - if you want to edit content, you first need a github account. Changing the website works like any other change to machinekit - using the normal C4 process: you create a Pull Request, which is merged by one of the maintainers, after which the changes are incorporated into the source of machinekit, or - in this case - the website.
You will find that almost all pages have an Edit this page link in the right column. Clicking the link leads you directly into edit mode on github - after you have made your changes, describe what they are about in the 'Commit changes' box at the bottom, 'Create a new branch for this commit and start a pull request', then click 'Propose file change'
Previewing changes
Opening a Pull Request triggers an update of the preview.machinekit.io Pull Request Preview site and your change should be online within minutes. This process is capable of only showing the latest PR - but the status of the preview formatting run is recorded in the PR status.
Going live: merge by maintainers
As soon as a maintainer gets around to merge your PR, the result is rendered on www.machinekit.io . This step takes slightly longer - but typically less than two minutes - as it runs a linkchecker step to analyze the site for broken links.
Contributing a large chunk of material: editing and previewing locally
The 'Edit this page' process is great for small changes. For big chunks of material - not so much. In this case it is best to set up jekyll-asciidoctor locally. The edit-preview turnaround is very quick - Instructions will follow here hortly !
Discussing improvements: use the docs tracker
Please go straight to these anchor issues depending on topic:
How this site is built
The docs repo is formatted by jekyll-asciidoctor; the resulting HTML is automatically pushed to Github to serve static content.
The jekyll installation is packaged into a docker container which contains a series of tools for embedded diagrams and source highlighting, for instance asciidoctor-diagram and pygments.
Some examples: