This repository contains the source code for the Cucumber Documentation website. It is currently live at https://docs.cucumber.io.
Please make ALL contributions to the documentation in docs.cucumber.io.
All relevant documentation from the old documentation has been added to this project and updated where needed. 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.
For various reasons, old Cucumber documentation was 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
With the new website being live, we're working on replacing the 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:
gem install bundler
brew install git hugo python
Hugo uses Pygments for syntax highlighting. Installing Pygments is optional - if you don't have it, code won't be highlighted.
pip install Pygments
If you don't have pip installed yet, you'll first need to install it.
On macOS you can do so by installing Python with Homebrew
brew install python
We use HTMLProofer to check whether hyperlinks are correct. To run HTMLProofer from the location of the project on your machine
make htmlproofer
If this doesn't work, you may need to install Ruby first:
gem install bundler
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).
make
If you are getting old errors, you might need to clean your files:
make clean
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, like with changes to the 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.
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.
Build notifications are sent to the #bots-website Slack channel. See
https://cucumber.io/support for details on how to access Slack.