Introduce a Notion specific file to register redirections as part of …

…the migration process (#8922)

We already have some code handling redirections, but for simplifying the
contribution process for teammates not too familiar with code, we
instead introduce a specific YAML file.

The format is dead simple, and should not pose any problems for anyone
to contribute.

```yaml
# data/notion_migration.yaml
redirections:
  - source: /departments/engineering/teams/devinfra
    destination: https://sourcegraph.notion.site/Developer-Infrastructure-Team-a46433b93bb2445abc1966c93a570a26
```

Additionally, the deprecation banner also recommend to teammates to
submit pull requests if they know the Notion equivalent of a given page:

<img width="873" alt="image"
src="https://github.com/sourcegraph/handbook/assets/10151/294e4093-6043-465d-b788-035133755570">

The separate file is practical for at a later stage, turning the
redirections in Cloudflare page rules, once we make
handbook.sourcegraph.com point at Notion instead of the legacy handbook
app.

---------

Co-authored-by: jhchabran <[email protected]>
Co-authored-by: Robert Lin <[email protected]>

README.md

@@ -6,6 +6,26 @@ The handbook is a living document and we expect every teammate to propose improv
 
 All content is in [Markdown](https://www.markdownguide.org/getting-started/#what-is-markdown) files under the [📁 content](./content) folder.
 
+## :warning: 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
+
+- [x] Set up basic Notion structure
+- [x] 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](https://app.slack.com/client/T02FSM7DL/CQ44Y7F4G) (for Sourcegraph team members), and/or [post an issue](https://github.com/sourcegraph/handbook/issues).

data/notion_migration.yaml

@@ -0,0 +1,6 @@
+# Add your desired redirections here!
+# - 'source': URL path to redirect, as currently visible on handbook.sourcegraph.com
+# - 'destination': New URL top direct to. If a public 'sourcegraph.notion.site' page is available, prefer that instead of the internal Notion URL.
+redirections:
+  - source: /departments/engineering/teams/devinfra
+    destination: https://sourcegraph.notion.site/Developer-Infrastructure-Team-a46433b93bb2445abc1966c93a570a26

src/components/Banner.tsx

@@ -21,7 +21,10 @@ export function Banner({ path }: { path: string }): JSX.Element {
                 <br />
                 The contents of this page will only be retained until <b>end of May 2024</b>. If you own this page,
                 please maintain an equivalent in the new{' '}
-                <a href="https://www.notion.so/sourcegraph">Notion-based handbook</a>.
+                <a href="https://www.notion.so/sourcegraph">Notion-based handbook</a>. You can set up a redirection to
+                the corresponding Notion page by making a pull request against{' '}
+                <a href="https://github.com/sourcegraph/handbook/blob/main/data/notion_migration.yml">this file</a> to
+                match the handbook path with the new Notion page.
             </div>
         </aside>,
     ]

src/scripts/redirects.mjs

@@ -1,3 +1,7 @@
+import { readFile } from 'fs/promises'
+
+import { load } from 'js-yaml'
+
 import { getMovedPagesFromHistory } from './getMovedPagesFromHistory.mjs'
 
 /**
@@ -24,15 +28,26 @@ export function cleanupRedirects(movedPages) {
     return [...redirects.entries()].map(([source, destination]) => ({ source, destination }))
 }
 
+/**
+ * Reads Notion specific redirections from data/notion_migration.yaml.
+ *
+ * @returns {redirections: {source: string, destination: string}[]}
+ */
+async function readNotionMigrationRedirects() {
+    return load(await readFile('data/notion_migration.yaml', 'utf8'))
+}
+
 /**
  * Returns all redirects that should be generated.
  *
  * @returns {Promise<{ source: string, destination: string }[]>}
  */
 export default async function redirects() {
     const movedPages = await getMovedPagesFromHistory()
+    const notionRedirections = await readNotionMigrationRedirects()
     return cleanupRedirects([
         ...movedPages,
+        ...notionRedirections.redirections,
 
         // Add custom redirects
         {