Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


A documentation site generator that fits Sourcegraph's needs:

  • Markdown source files that are browseable on the file system and readable as plain text (without custom directives or complex front matter or configuration)
  • Served by an HTTP server, not generated as static HTML files, to eliminate the need for external static site host configuration (which we found to be error-prone)
  • Provides built-in site search for all documentation versions


go get
docsite -h
  • docsite check: check for common problems (such as broken links)
  • docsite serve: serve the site over HTTP

To use docsite for, see "Documentation site" in the Sourcegraph documentation.


The docsite check command runs various checks on your documentation site to find problems:

  • invalid links
  • broken links
  • disconnected pages (with no inlinks from other pages)

If any problems are found, it exits with a non-zero status code.

To ignore the disconnected page check for a page, add YAML ignoreDisconnectedPageCheck: true to the top matter in the beginning of the .md file. For example:

ignoreDisconnectedPageCheck: true

# My page title

Site data

The site data describes the location of its templates, assets, and content. It is a JSON object with the following properties.

  • content: a VFS URL for the Markdown content files.
  • contentExcludePattern: a regular expression specifying Markdown content files to exclude.
  • baseURLPath: the URL path where the site is available (such as / or /help/).
  • rootURL: (optional) the root URL (scheme + host). Only used for rare cases where this is absolutely necessary, such as SEO tags fox example.
  • templates: a VFS URL for the Go-style HTML templates used to render site pages.
  • assets: a VFS URL for the static assets referred to in the HTML templates (such as CSS stylesheets).
  • assetsBaseURLPath: the URL path where the assets are available (such as /assets/).
  • redirects: an object mapping URL paths (such as /my/old/page) to redirect destination URLs (such as /my/new/page).
  • check (optional): an object containing a single property ignoreURLPattern, which is a RE2 regexp of URLs to ignore when checking for broken URLs with docsite check.
  • search (optional): an object containing a single proprety skipIndexURLPattern, which is a RE2 regexp pattern that if matching any content file URL will remove that file from the search index.

The possible values for VFS URLs are:

  • A relative path to a local directory (such as ../myrepo/doc). The path is interpreted relative to the docsite.json file (if it exists) or the current working directory (if site data is specified in DOCSITE_CONFIG).

  • An absolute URL to a Zip archive (with http or https scheme). The URL can contain a fragment (such as #mydir/) to refer to a specific directory in the archive.

    If the URL fragment contains a path component * (such as #*/templates/), it matches the first top-level directory in the Zip file. (This is useful when using GitHub Zip archive URLs, such as*/templates/. GitHub produces Zip archives with a top-level directory $REPO-$REV, such as myrepo-myrev, and using #*/templates/ makes it easy to descend into that top-level directory without needing to duplicate the myrev in the URL fragment.)

    If the URL contains the literal string $VERSION, it is replaced by the user's requested version from the URL (e.g., the URL path /@foo/bar means the version is foo). ⚠️ If you are using GitHub archive URLs, be sure your URL contains refs/heads/$VERSION (as in$VERSION), not just $VERSION. This prevents someone from forking your repository, pushing a commit to their fork with unauthorized content, and then crafting a URL on your documentation site that would cause users to view that unauthorized content (which may contain malicious scripts or misleading information).


The templates use Go-style HTML templates.

  • Document pages are rendered using a template named document.html.
  • Search result pages are rendered using a template named search.html.
  • The file root.html, if it exists, is loaded when rendering any template. You can define common templates in this file.

See the following examples:


In addition to the redirects property in site data, you can also specify redirects in a text file named redirects at the top level of the assets VFS. The format is as follows:


For example:

# Comments are allowed
/my/old/page /my/new/page 308
/another/page 308

Specifying site data

The docsite tool requires site data to be available in any of the following ways:

  • A docsite.json file (or other file specified in the -config flag's search paths), as in the following example:
      "content": "../sourcegraph/doc",
      "baseURLPath": "/",
      "templates": "templates",
      "assets": "assets",
      "assetsBaseURLPath": "/assets/",
      "check": {
        "ignoreURLPattern": "(^https?://)|(^#)|(^mailto:support@sourcegraph\\.com$)|(^chrome://)"
  • In the DOCSITE_CONFIG env var, using Zip archive URLs for templates, assets, and content, as in the following example:
    DOCSITE_CONFIG='{"templates":"*/doc/_resources/templates/","assets":"*/doc/_resources/assets/","content":"$VERSION#*/doc/","baseURLPath":"/","assetsBaseURLPath":"/assets/","defaultContentBranch":"main"}' docsite serve


Release a new version

docker build -t sourcegraph/docsite . && \
docker push sourcegraph/docsite && \
docker tag sourcegraph/docsite && \
gcloud docker -- push

For internal Sourcegraph usage, bump the deployed version by updating the SHA-256 image digest in all files that define sourcegraph/docsite:latest@sha256.

For development, bump the version number in files that define DOCSITE_VERSION.