Product documentation guidelines

The documentation guidelines apply to product documentation. This page has information specific to this repository's documentation.

Documentation directory structure

The documentation is organized into the following top-level directories:

  • user/ for users
  • admin/ for site admins
    • external_service/ for documentation for connecting Sourcegraph to code hosts and Phabricator (for site admins).
  • extensions/ for Sourcegraph extensions
  • integration/ for integrations with other products, targeted at the general audience (vs. admin/external_service/ for site admin-specific docs)
  • api/ for the Sourcegraph GraphQL API

Previewing changes locally

You can preview the documentation site at http://localhost:5080 when running Sourcegraph in local development (using dev/start.sh or enterprise/dev/start.sh). It uses content, templates, and assets from the local disk. There is no caching or background build process, so you'll see all changes reflected immediately after you reload the page in your browser.

Linking to documentation in-product

In-product documentation links should point to /help/PATH instead of using an absolute URL of the form https://docs.sourcegraph.com/PATH. This ensures they link to the documentation for the current product version. There is a redirect (when using either <a> or react-router <Link>) from /help/PATH to the versioned docs.sourcegraph.com URL (https://docs.sourcegraph.com/@VERSION/PATH).

Updating documentation

To update documentation content, templates, or assets on https://docs.sourcegraph.com, push changes in the doc/ directory to this repository's master branch, then wait up to 5 minutes. Every 5 minutes, docs.sourcegraph.com reloads all content, templates, and assets from master.

  • Documentation content lives in doc/**/*.md.
  • Assets and templates live in doc/_resources/{templates,assets}.

Advanced 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