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

⚠️ Ongoing migration to Notion.so

We are in the process of moving the handbook over Notion.so. In the original spirit of the handbook, we want most pages to stay publicly accessible.

• If you intend to contribute to the handbook, please instead do so on the Notion corresponding page, or port it if that's not yet done.
• If you maintain a set of pages, please take some time to add the corresponding redirection to the Notion equivalent in [data/notion_migration.yaml].

Plan

• Set up basic Notion structure
• Port the most important pages
• [] Port the remaining content
• Populate redirections for important pages to their Notion equivalent.
• May 1st: pull request for content change are subject to strict review.
  • Only necessary changes are allowed.
• May 15th: content changes are forbidden, only redirections are accepted.
• May 31th: repository is archived.
• handbook.sourcegraph.com is now serving Notion pages.
  • Previously set redirections are ported from the application to Cloudflare page rules.

Need help editing?

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

Run or develop locally

Setup

1. Install asdf
2. 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.