This repository contains the source code for https://cucumber.io/docs.
If you want to read the docs, go there. ☝🏼
For small edits, the recommended way to contribute is via GitHub. Each page in the documentation will have an Edit link for this purpose.
For bigger modifications, the recommended workflow is to edit the documentation locally on your machine, and seeing the results in a web browser.
This involves getting the source code and building the documentation yourself.
Get the source code
git clone https://github.com/cucumber/docs cd docs
View the site
The website is built with several tools that are distributed as a Docker image.
Install Docker if you don't already have it on your machine.
Build and serve the website:
Open a browser:
Changes to the contents will be automatically updated in the browser.
Try editing one of the pages under
content and see for yourself!
Build the site and check links
When you are done editing, build the site and check links:
./docker_shell.sh make clean ./docker_shell.sh make ./docker_shell.sh make htmlproofer
By default, external links are only checked in CI (because it takes a while). To check external links locally:
CI=true ./docker_shell.sh make htmlproofer
Links that are broken should be removed or replaced, even if they are only temporarily broken. The reason for this is that broken links negatively affect search engine rankings.
See the theme README
The site is built with Hugo, a fast static site generator.
We have a custom-built theme for the site in
themes/cucumber-hugo. This theme
is based on Bulma - a lightweight CSS framework.
The online site is rebuild automatically whenever the git repository receives
new commits, either via a
git push, or by modifying contents in the CMS.
The Netlify CMS saves contents straight to GitHub using the GitHub API.
GitHub will notify Netlify for every
git push thanks to a webhook.
Netlify will then build the site and deploy it if the build is successful.
The build will check for broken links and other problems. Internal and external links are checked by HTMLProofer. Occasionally, the build will fail due to external links being unavailable or giving a timeout. When that happens, please check if these external links are available and if so, 'Retry build' on Netlify.