dcsg / docs

concourse documentation and website

Concourse Docs

This is where you will find the source for the Concourse website and overall documentation. All of our docs are written using the Booklit documentation engine.

Table of Contents

• Building the Docs Locally
• Docs Styling
• Content Layout

Examples Status

• git-triggered
• golang-lib
• hooks
• java
• job
• manual-trigger
• nodejs
• php
• pipeline-vars
• rails
• serial-job
• task-passing-artifact
• time-triggered

Building the Docs Locally

Prerequisites

• Have Go v1.11.2+ installed and configured. You can find the relevant instructions for your platform of choice here: Go Getting Started

• Clone this repository: https://github.com/concourse/docs

Compiling the Docs

You can compile the Concourse docs by running:

./scripts/build

The build script will instruct Booklit to compile all the files under lit/ as html files. The files will then be dumped into your current working directory, i.e. the root of this repo.

Viewing the docs in your browser

To run a server that will rebuild the docs as needed, pass -s (port) like so:

./scripts/build -s 8000

You will be now be able to see the rendered site if you navigate to http://localhost:8000.

Docs Styling

You can find all of the styling assets for the Concourse website and documentation under the css/ folder.

If you are planning to make changes to the site, css/booklit.css is usually a good place to start.

Content Layout

All of the website content can be found under the lit/ folder of this repository.

The content layout for the site is qute simple, and for the most part self-explanatory. If you want to change a specific page on the website you can usually jump straight to it by looking for the .lit version of the page. For example you can make changes to https://concourse-ci.org/fly.html by editing lit/fly.lit.

• html/docs-header.tmpl L1 navigation header for the Concourse website and docs.
• lit/index.html The Concourse Homepage
• lit/reference/ This is where you'll find most of the documentation listed under https://concourse-ci.org/reference.html
• lit/release-notes/ Release notes separated by Concourse version. These .lit snippets are ultimately loaded into lit/download.lit
• lit/download.lit/ Concourse Downloads page
• lit/docs/resource-types/community-resources.lit A listing of Concourse community-supported resources

Updating the Blog Theme

$ make blog/concourse.zip
# and then upload it in the Ghost admin UI

Updating the Discourse Theme

$ gem install discourse_theme
$ discourse_theme watch concourse
? What is the root URL of your Discourse site? https://discuss.concourse-ci.org
? Would you like this site name stored in /home/.../.discourse_theme? Yes
» Using api key from /home/.../.discourse_theme
? How would you like to sync this theme? Select a different theme
? Which theme would you like to sync with? Concourse (id:12)
» Uploading theme from /home/alex/src/docs/discourse
✔ Theme uploaded (id:12)
» Watching for changes in /home/alex/src/docs/discourse...
^C✘ Interrupted