Documentation site

Our documentation site (https://docs.sourcegraph.com) runs docsite.

See “Updating documentation” and “Previewing changes locally” for the most common workflows involving the documentation site.

Forcing immediate reload of data

The docs.sourcegraph.com site reloads content, templates, and assets every 5 minutes. After you push a documentation update, just wait up to 5 minutes to see your changes reflected on docs.sourcegraph.com.

If you can’t wait 5 minutes and need to force a reload, you can kill the docs-sourcegraph-com-* Kubernetes pod on the Sourcegraph.com Kubernetes cluster. (It will restart and come back online with the latest data.)

Other ways of previewing changes locally (very rare)

The local documentation server on http://localhost:5080 only serves a single version of the documentation (from the doc/ directory of your working tree). This usually suffices.

In very rare cases, you may want to run a local documentation server with a different configuration (described in the following sections).

Running a local server that mimics prod configuration

If you want to run the doc site exactly as it’s deployed (reading templates and assets from the remote Git repository, too), consult the current Kubernetes deployment spec and invoke docsite serve with the deployment’s DOCSITE_CONFIG env var, the end result looking something like:

DOCSITE_CONFIG=$(cat <<-'DOCSITE'
{
  "templates": "https://codeload.github.com/sourcegraph/sourcegraph/zip/master#*/doc/_resources/templates/",
  "assets": "https://codeload.github.com/sourcegraph/sourcegraph/zip/master#*/doc/_resources/assets/",
  "content": "https://codeload.github.com/sourcegraph/sourcegraph/zip/refs/heads/$VERSION#*/doc/",
  "baseURLPath": "/",
  "assetsBaseURLPath": "/assets/"
}
DOCSITE
) docsite serve -http=localhost:5081