The documentation guidelines apply to product documentation. This page has information specific to this repository's documentation.
The documentation is organized into the following top-level directories:
user/
for usersadmin/
for site admins
external_service/
for documentation for connecting Sourcegraph to code hosts and Phabricator (for site admins).extensions/
for Sourcegraph extensionsintegration/
for integrations with other products, targeted at the general audience (vs. admin/external_service/
for site admin-specific docs)api/
for the Sourcegraph GraphQL APIYou 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.
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).
We generally try to avoid adding large binary files to our repository. Images to be used in documentation fall under that category, but there can be exceptions if the images are small.
./doc
folder.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
.
doc/**/*.md
.doc/_resources/{templates,assets}
.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.
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.)
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).
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