The source files for the Buildkite Documentation.
To contribute, send a pull request!
Development
Before you start
For containerized development, you need Docker and Docker Compose.
Most desktop installations of Docker include Docker Compose by default.
On some platforms, you may need to prefix docker
commands with sudo
or add your user to the docker
group.
For non-containerized development, you need Ruby.
See .ruby-version
for the current required version
or use rbenv
to automatically select the correct version of Ruby
Run the development server
-
Get the source. Run:
git clone https://github.com/buildkite/docs.git cd docs git submodule update --init
-
Build and run the server.
For non-containerized development, run:
# Install the dependencies bundle # Start the app on http://localhost:3000/ bin/rails server
Or with Docker, run:
# Start the app on http://localhost:3000/ docker-compose up --build
Open http://localhost:3000
to preview the docs site.
After modifying a page, refresh to see your changes.
Note: By default, search (through Algolia) does not work in development.
Updating buildkite-agent CLI Docs
With the development dependencies installed you can update the CLI docs using
script/update-agent-help.sh
:
# Set a custom PATH to select a locally built buildkite-agent
PATH="$HOME/Projects/buildkite/agent:$PATH" ./script/update-agent-help.sh
Linting
We spell-check the docs (American English) and run a few automated checks for repeated words, common errors, and markdown and filename inconsistencies.
You can run most of these checks with ./scripts/vale.sh
.
If you've added a new valid word that showing up as a spelling error, add it to vale/vocab.txt
.
Style guide
Our documentation is based on the principles of common sense, clarity, and brevity.
The style guide should provide you a general idea and an insight into using custom formatting elements.
Search index
The search index is updated once a day by a scheduled build using the config in config/algolia.json
.
To test changes to the indexing configuration:
-
Make sure you have an API key in
.env
like:APPLICATION_ID=APP_ID API_KEY=YOUR_API_KEY
-
Run
bundle exec rake update_test_index
.
License
See LICENSE.md (MIT)