📘 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.

⚠️ Migration to Notion.so

The handbook is hosted on Notion, and https://handbook.sourcegraph.com will redirect to the corresponding Notion.site. Redirections listed in data/notion_migration.yaml are now handled through Cloudflare.

Please reach-out to #wg-notion to add a new one if:

It's a very important page that was relevant to customers.
It's a very important page for the hiring process and emails are in-flight with those URLs.

Please reach-out to #discuss-dev-infra directly if:

You need to scrub content from the handbook (incorrect content has been added before the repo was archived).
You absolutely need to push some change, with a very valid reason for it.

Need help editing?

Ask in the #handbook channel (for Sourcegraph team members), and/or post an issue.

Run or develop locally

Setup

Install asdf
Run asdf plugin add nodejs && asdf plugin add pnpm && asdf install

Running the website locally

Run:

pnpm install
pnpm dev

Then open http://localhost:3000 in your web browser.

Development notes

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:

pnpm 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:

pnpm 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.

Build

During deployment, the netlify-build script gets executed. To simulate the build process, you can run it locally:

pnpm netlify-build

The output will be in the out directory.

Deployment to production

The repository is configured to automatically deploy the main branch to production on Netlify.

sourcegraph/handbook