dannyfallon/docs

The source files for the Buildkite documentation

Buildkite Documentation

The source files for the Buildkite Documentation.

To contribute, send a pull request! ❤️

Development

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

Note: If you're having trouble with an installation on an M1 Mac, use rbenv instead of the Ruby version provided by macOS or Homebrew.

If you have Ruby installed:

# Navigate into the docs directory
# Install the dependencies
bundle
# Run the specs
bundle exec rspec
# Start the app on http://localhost:3000/
bin/rails server

Note: Check .ruby-version for the current required version. You also need Node installed. The current LTS (long term support) version should be ok.

If you have Docker installed:

# Start the app on http://localhost:3000/
docker-compose up --build
# To start it in production mode on http://localhost:3000/
docker-compose -f docker-compose.production.yml up --build

Note: You need to use sudo if your username is not added to the docker group.

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:

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.

License

See LICENSE.md (MIT)