https://github.com/sourcegraph/handbook

📘 The Sourcegraph handbook
https://github.com/sourcegraph/handbook

Last synced: 7 days ago
JSON representation

📘 The Sourcegraph handbook

• Host: GitHub
• URL: https://github.com/sourcegraph/handbook
• Owner: sourcegraph
• License: apache-2.0
• Created: 2021-09-27T17:18:33.000Z (about 3 years ago)
• Default Branch: main
• Last Pushed: 2024-04-12T20:19:09.000Z (7 months ago)
• Last Synced: 2024-04-14T06:53:26.617Z (7 months ago)
• Language: TypeScript
• Homepage: https://handbook.sourcegraph.com
• Size: 34.1 MB
• Stars: 132
• Watchers: 50
• Forks: 104
• Open Issues: 93
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-handbooks - sourcegraph
• jimsghstars - sourcegraph/handbook - 📘 The Sourcegraph handbook (TypeScript)

README

        
# 📘 Sourcegraph handbook 

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 

```

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.