Buildkite Documentation

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.

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)

matclayton/docs