This repository contains the source code for the Cucumber Documentation website. It is currently live at https://cucumber.netlify.com, and the plan is to move it to https://docs.cucumber.io once it is good enough to replace the existing documentation.
Please make ALL contributions to the documentation in docs.cucumber.io.
We are working to add and update all of the old documentation (see below) to this repo.
All relevant documentation from the old documentation has been added to this project. Some files have been deleted; this does not necessarily mean that those files should not exist, just that there was not enough info there to justify leaving them.
This work is currently being done and has been merged to master.
For various reasons, old Cucumber documentation is scattered around different places:
- 2008 onwards: Cucumber wiki (primarily Ruby)
- 2008 onwards: Misc README files for different implementations:
- 2015 onwards: https://cucumber.io/docs
- Based on our own website app (Jekyll-like)
- source
- 2016 onwards: https://docs.cucumber.io/
- Based on GitBook
- source
- See SUMMARY.md for the outline
The goal is to move the documentation to this repo.
When the new website is ready to go live, we should replace contents on old pages with a link and/or redirect to the new location, so that external links to the old documentation remain useful.
The easiest way to contribute content is to add or modify content in the Netlify CMS.
Alternatively, you can clone this repo and edit Markdown files in a text editor on your local machine
If you want to modify layout, or prefer to work in a text editor you need to install some software.
git clone https://github.com/cucumber/docs.cucumber.io.git
cd docs.cucumber.io
The site is built with Hugo. Install it:
brew install git hugo
Hugo uses Pygments for syntax highlighting. Installing Pygments is optional - if you don't have it, code won't be highlighted.
pip install Pygments
Start the server:
hugo server
Open a browser:
http://localhost:1313
Edit Markdown files under in the content directory.
Whenever you make a change to the content, the server will automatically rebuild the site (in a few milliseconds) and tell the browser to reload (using a WebSocket).
Edit files under themes/cucumber-hugo. Changes to the CSS should be made in
themes/cucumber-hugo/static/css/cucumber.sass.
If you make changes to the sass, it will be rebuilt if you run the following:
cd themes/cucumber-hugo
yarn # install dependencies
yarn build # rebuild cucumber.css
A rebuild of the CSS will trigger a reload of the browser, just like with content.
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.
We might experiment with other CMS systems if Netlify CMS doesn't fit with our workflow.
GitHub will notify Netlify for every git push via a [webhook](thanks to a webhook).
Netlify will then build the site 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.
Build notifications are sent to the #cucumber-docs-bots Slack channel. See
https://cucumber.io/support for details on how to access Slack.