📘 Sourcegraph handbook

The Sourcegraph handbook describes how we (Sourcegraph teammates) work. It’s publicly visible because we are an open company.

The handbook is a living document and we expect every teammate to propose improvements, changes, additions, and fixes to keep it continuously up-to-date and accurate.

All content is in Markdown files under the 📁 content folder.

Run locally

You need NodeJS and Yarn installed. How to do so can vary from machine to machine, but as an example on Ubuntu 20.04:

Install nvm from https://github.com/nvm-sh/nvm
Run nvm install from the current directory
Run npm install -g yarn from the current directory

Install dependencies:

yarn

Then start the handbook:

yarn dev

Autogenerated content

There are special tokens within some markdown pages ({{generator:*}}) that are filled at build time from the YAML files in the data folder. The code which does this the filling is in [src/lib/generatedMarkdown.ts], and these are called as part of the markdown pipeline in src/lib/markdownToHtml.ts.

Check links locally

We use markdown-link-check for link checking at build time in the link-check GitHub action. If you want to run it locally, from the root of the repository you can run this command:

yarn check-links

This can be slow, so you can also check a single file by running this command, replacing path_to_file with the file you want to validate:

yarn markdown-link-check <path_to_file>

Note that this will also check external links, which the GitHub action ignores. If you wish to ignore those, add -c .github/workflows/link-check-internal.json to the command.