# handbook

**Repository Path**: mirrors_sourcegraph/handbook

## Basic Information

- **Project Name**: handbook
- **Description**: 📘 The Sourcegraph handbook
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-12-20
- **Last Updated**: 2026-04-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📘 Sourcegraph handbook <a href="https://app.netlify.com/sites/sourcegraph-handbook/deploys"><img alt="Netlify Status" src="https://api.netlify.com/api/v1/badges/4c81a998-33b5-4357-a593-479e21bb10f3/deploy-status" align="right"></a>

The Sourcegraph handbook describes how we (Sourcegraph teammates) work. It’s publicly visible because we are an [open company](https://handbook.sourcegraph.com/company#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](https://www.markdownguide.org/getting-started/#what-is-markdown) files under the [📁 content](./content) folder.

## :warning: 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](https://sourcegraph.slack.com/archives/C06T68DBMSA) 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](https://sourcegraph.slack.com/archives/C04MYFW01NV) 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](https://app.slack.com/client/T02FSM7DL/CQ44Y7F4G) (for Sourcegraph team members), and/or [post an issue](https://github.com/sourcegraph/handbook/issues).

## Run or develop locally

### Setup

1. Install [asdf](https://asdf-vm.com/)
1. Run `asdf plugin add nodejs && asdf plugin add pnpm && asdf install`

### Running the website locally

Run:

```sh
pnpm install
pnpm dev
```

Then open [http://localhost:3000](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](./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](https://github.com/tcort/markdown-link-check) for link checking at build time in [the `link-check` GitHub action](.github/workflows/link-check.yml). If you want to run it locally, from the root of the repository you can run this command:

```shell
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:

```shell
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:

```shell
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.