The source files for the Buildkite Documentation.

To contribute, send a pull request! ❤️

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

1. Get the source. Run:

   git clone https://github.com/buildkite/docs.git
   cd docs
   git submodule update --init

2. Build and run the server.

   For non-containerized development, run:

   # Install the dependencies
   bundle
   # Start the app on https://localhost:3000/
   bin/rails server

   Or with Docker, run:

   # Start the app on https://localhost:3000/
   docker-compose up --build

Open https://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.

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

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.

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.

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:

1. Make sure you have an API key in .env like:

   APPLICATION_ID=APP_ID
   API_KEY=YOUR_API_KEY

2. Run bundle exec rake update_test_index.

See LICENSE.md (MIT)