Tweak folder structure + widen sidebar, shorten sidebar titles + upda…

…te CONTRIBUTING and LICENSE (#885)

* Apply AK’s structure changes and shorter sidebar titles + update links and redirects

* Widen sidebar

* Update CONTRIBUTING and LICENSE

CONTRIBUTING.md

@@ -1,25 +1,36 @@
 # Contributing to The Graph Docs
 
-Welcome to the Graph Protocol! Thanks so much for helping us improve our documentation. Any contribution to this project, when it’s approved and merged, will eventually be visible on [https://thegraph.com/docs](https://thegraph.com/docs).
+Welcome to The Graph! Thanks so much for helping us improve our documentation. Any contribution to this project, when it’s approved and merged, will eventually be visible on [https://thegraph.com/docs](https://thegraph.com/docs).
 
-Please read and follow our [Code of Conduct](https://github.com/graphprotocol/graph-node/blob/master/CODE_OF_CONDUCT.md) to keep our community approachable and respectable.
+Direct contributions are much appreciated for simple things (corrections, small additions to existing content). If the change is more complex, we encourage you to start a discussion in GitHub Issues or Discord first.
 
-## Contributor’s Guide
+## Making changes
 
-Most of our docs are written in Markdown. If you are not familiar with Markdown, learn more [here](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). The files that you’ll likely be updating are inside of the “pages” folder. From there select a language in order to view the Markdown files.
+Most of our docs are written in [Markdown](https://www.markdownguide.org/getting-started/), or more specifically, [MDX](https://mdxjs.com/docs/what-is-mdx/). The files that you’ll likely be updating are in [the `/website/src/pages/en` directory](https://github.com/graphprotocol/docs/tree/main/website/src/pages/en).
 
-Direct contributions are much appreciated for simple things (corrections, small additions to existing content). If the change is more complex, we encourage you to start a discussion in GitHub Issues or Discord first.
+> [!NOTE]
+>
+> Changes should only be made to the English language version of pages, as translations are handled by [Crowdin](https://crowdin.com/). If you spot an issue with a translation, please open an issue to let us know!
 
-Change proposals should only be made to the English language version of pages (under `/pages/en/`), as translations are handled by [Crowdin](https://crowdin.com/). If you spot an issue with a translation, please do open an issue to let us know!
+Once you located the file that you want to update, click on “Edit” which will create a new forked repo. You can make your edits there, and submit a PR. Alternatively, you can manually fork the repo, create a branch in your fork and make all the edits you want before submitting a PR. You can optionally [run the application locally](https://github.com/graphprotocol/docs/blob/main/README.md) to review your changes in context.
 
-## Making changes
+## Adding new pages
+
+When adding a new page, you should also add it to the sidebar navigation. This is done by adding an entry to the JavaScript object exported by the `_meta.js` file found in the directory of the file you created, where the key is the filename (minus the `.mdx` extension) and the value is an empty string. The `_meta.js` files control the order of the sidebar items. To give your new page a different title in the navigation (in case the full title is too long), you should add a `sidebarTitle` property to the [frontmatter](https://mdxjs.com/guides/frontmatter/) of the page, below `title`.
+
+## Moving or renaming pages or directories
+
+If you want to make larger changes that involve moving or renaming pages or directories, you should use the `pnpm run move-pages` script in the `website` package (`cd website && pnpm run move-pages`; example usage is provided when running the script with no arguments). This will move/rename files/directories in all languages simultaneously, which is necessary to prevent build errors.
 
-Once you located the file that you want to update, click on “Edit” which will create a new forked repo. You can make your edits there, and submit a PR. Alternatively, you can manually fork the repo, create a branch in your fork and make all the edits you want before submitting a PR.
+> [!NOTE]
+>
+> It is technically possible to manually move/rename files in English only and then fix the build with the `pnpm run fix-pages-structure` script, but translations for the moved/renamed pages will be lost in the process.
 
-Tag `graphprotocol/docs-reviewers` in your PR to get the reviewers’ attention. Once we review it, we’ll likely provide feedback and might ask you for improvements. Once the review process is finalized and at least 2 people approve, the PR will be merged. We aim to provide a meaningful response to all PRs and issues from external contributors within 5 business days.
+Since URLs are generated from the file structure, you should also do the following _for every URL change_ in a PR that moves or renames pages:
 
-You can optionally [run the application locally](https://github.com/graphprotocol/docs/blob/main/README.md) to review your changes.
+- Update all links across docs pages, from the old URL to the new URL (e.g. `[see the Delegating page](/old/delegating/)` => `[see the Delegating page](/new/delegating/)`).
+- Add a redirect from the old URL to the new URL in the `nginx.conf` file.
 
 ## Creating an issue
 
-If you would like to report a bug, or propose a larger feature, please create an issue. Before doing so, please search existing issues for relevant keywords, in case your issue has already been raised by someone else.
+If you would like to report a bug, or propose a larger feature, please create an issue. Before doing so, please search existing issues for relevant keywords, in case your issue was already raised by someone else.

LICENSE-MIT

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2018 Graph Protocol, Inc. and contributors.
+Copyright (c) 2025 The Graph Foundation and contributors.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -34,4 +34,4 @@ Then, run the project:
 pnpm dev
 ```
 
-That’s it! Go to http://localhost:3000 to see it in action. Any change you make to a file in `pages` should be refreshed automatically in your browser.
+That’s it! Go to http://localhost:3000/docs to see it in action. Any change you make to a file in `website/src/pages` should be refreshed automatically in your browser.

nginx.conf

@@ -59,26 +59,33 @@ http {
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/billing/$                                     $scheme://$http_host/docs/$1/subgraphs/billing/                                     permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/chain-integration-overview/$                  $scheme://$http_host/docs/$1/indexing/chain-integration-overview/                   permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/arweave/$                            $scheme://$http_host/docs/$1/subgraphs/cookbook/arweave/                            permanent;
-        rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/avoid-eth-calls/$                    $scheme://$http_host/docs/$1/subgraphs/cookbook/avoid-eth-calls/                    permanent;
-        rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/derivedfrom/$                        $scheme://$http_host/docs/$1/subgraphs/cookbook/derivedfrom/                        permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/avoid-eth-calls/$                    $scheme://$http_host/docs/$1/subgraphs/best-practices/avoid-eth-calls/              permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/subgraphs/cookbook/avoid-eth-calls/$          $scheme://$http_host/docs/$1/subgraphs/best-practices/avoid-eth-calls/              permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/derivedfrom/$                        $scheme://$http_host/docs/$1/subgraphs/best-practices/derivedfrom/                  permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/subgraphs/cookbook/derivedfrom/$              $scheme://$http_host/docs/$1/subgraphs/best-practices/derivedfrom/                  permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/enums/$                              $scheme://$http_host/docs/$1/subgraphs/cookbook/enums/                              permanent;
-        rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/grafting-hotfix/$                    $scheme://$http_host/docs/$1/subgraphs/cookbook/grafting-hotfix/                    permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/grafting-hotfix/$                    $scheme://$http_host/docs/$1/subgraphs/best-practices/grafting-hotfix/              permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/subgraphs/cookbook/grafting-hotfix/$          $scheme://$http_host/docs/$1/subgraphs/best-practices/grafting-hotfix/              permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/grafting/$                           $scheme://$http_host/docs/$1/subgraphs/cookbook/grafting/                           permanent;
-        rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/immutable-entities-bytes-as-ids/$    $scheme://$http_host/docs/$1/subgraphs/cookbook/immutable-entities-bytes-as-ids/    permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/immutable-entities-bytes-as-ids/$    $scheme://$http_host/docs/$1/subgraphs/best-practices/immutable-entities-bytes-as-ids/ permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/subgraphs/cookbook/immutable-entities-bytes-as-ids/$ $scheme://$http_host/docs/$1/subgraphs/best-practices/immutable-entities-bytes-as-ids/ permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/near/$                               $scheme://$http_host/docs/$1/subgraphs/cookbook/near/                               permanent;
-        rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/pruning/$                            $scheme://$http_host/docs/$1/subgraphs/cookbook/pruning/                            permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/pruning/$                            $scheme://$http_host/docs/$1/subgraphs/best-practices/pruning/                      permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/subgraphs/cookbook/pruning/$                  $scheme://$http_host/docs/$1/subgraphs/best-practices/pruning/                      permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/quick-start/$                        $scheme://$http_host/docs/$1/subgraphs/quick-start/                                 permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/subgraph-debug-forking/$             $scheme://$http_host/docs/$1/subgraphs/cookbook/subgraph-debug-forking/             permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/subgraph-uncrashable/$               $scheme://$http_host/docs/$1/subgraphs/cookbook/subgraph-uncrashable/               permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/substreams-powered-subgraphs/$       $scheme://$http_host/docs/$1/subgraphs/cookbook/substreams-powered-subgraphs/       permanent;
-        rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/timeseries/$                         $scheme://$http_host/docs/$1/subgraphs/cookbook/timeseries/                         permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/timeseries/$                         $scheme://$http_host/docs/$1/subgraphs/best-practices/timeseries/                   permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/subgraphs/cookbook/timeseries/$               $scheme://$http_host/docs/$1/subgraphs/best-practices/timeseries/                   permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/transfer-to-the-graph/$              $scheme://$http_host/docs/$1/subgraphs/cookbook/transfer-to-the-graph/              permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/curating/$                                    $scheme://$http_host/docs/$1/resources/roles/curating/                              permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/delegating/$                                  $scheme://$http_host/docs/$1/resources/roles/delegating/delegating/                 permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/deploying/deploy-using-subgraph-studio/$      $scheme://$http_host/docs/$1/subgraphs/developing/deploying/using-subgraph-studio/  permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/deploying/deploying-a-subgraph-to-studio/$    $scheme://$http_host/docs/$1/subgraphs/developing/deploying/using-subgraph-studio/  permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/deploying/multiple-networks/$                 $scheme://$http_host/docs/$1/subgraphs/developing/deploying/multiple-networks/      permanent;
-        rewrite ^/docs/([a-zA-Z][a-zA-Z])/deploying/subgraph-studio-faqs/$              $scheme://$http_host/docs/$1/subgraphs/developing/deploying/subgraph-studio-faq/    permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/deploying/subgraph-studio-faqs/$              $scheme://$http_host/docs/$1/resources/subgraph-studio-faq/                         permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/subgraphs/developing/deploying/subgraph-studio-faq/$ $scheme://$http_host/docs/$1/resources/subgraph-studio-faq/                  permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/deploying/subgraph-studio/$                   $scheme://$http_host/docs/$1/subgraphs/developing/deploying/using-subgraph-studio/  permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/developing/assemblyscript-api/$               $scheme://$http_host/docs/$1/subgraphs/developing/creating/graph-ts/api/            permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/developing/creating-a-subgraph/$              $scheme://$http_host/docs/$1/subgraphs/developing/creating/starting-your-subgraph/  permanent;
@@ -127,18 +134,21 @@ http {
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/querying/querying-the-graph/$                 $scheme://$http_host/docs/$1/subgraphs/querying/introduction/                       permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/querying/querying-with-python/$               $scheme://$http_host/docs/$1/subgraphs/querying/python/                             permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/quick-start/$                                 $scheme://$http_host/docs/$1/subgraphs/quick-start/                                 permanent;
-        rewrite ^/docs/([a-zA-Z][a-zA-Z])/release-notes/assemblyscript-migration-guide/$ $scheme://$http_host/docs/$1/resources/release-notes/assemblyscript-migration-guide/ permanent;
-        rewrite ^/docs/([a-zA-Z][a-zA-Z])/release-notes/graphql-validations-migration-guide/$ $scheme://$http_host/docs/$1/resources/release-notes/graphql-validations-migration-guide/ permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/release-notes/assemblyscript-migration-guide/$ $scheme://$http_host/docs/$1/resources/migration-guides/assemblyscript-migration-guide/ permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/resources/release-notes/assemblyscript-migration-guide/$ $scheme://$http_host/docs/$1/resources/migration-guides/assemblyscript-migration-guide/ permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/release-notes/graphql-validations-migration-guide/$ $scheme://$http_host/docs/$1/resources/migration-guides/graphql-validations-migration-guide/ permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/resources/release-notes/graphql-validations-migration-guide/$ $scheme://$http_host/docs/$1/resources/migration-guides/graphql-validations-migration-guide/ permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/sps/triggers-example/$                        $scheme://$http_host/docs/$1/sps/tutorial/                                          permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/studio/billing/$                              $scheme://$http_host/docs/$1/subgraphs/billing/                                     permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/studio/deploy-subgraph-studio/$               $scheme://$http_host/docs/$1/subgraphs/developing/deploying/using-subgraph-studio/  permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/studio/managing-api-keys/$                    $scheme://$http_host/docs/$1/subgraphs/querying/managing-api-keys/                  permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/studio/multisig/$                             $scheme://$http_host/docs/$1/subgraphs/cookbook/multisig/                           permanent;
-        rewrite ^/docs/([a-zA-Z][a-zA-Z])/studio/studio-faq/$                           $scheme://$http_host/docs/$1/subgraphs/developing/deploying/subgraph-studio-faq/    permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/studio/studio-faq/$                           $scheme://$http_host/docs/$1/resources/subgraph-studio-faq/                         permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/studio/subgraph-studio/$                      $scheme://$http_host/docs/$1/subgraphs/developing/deploying/using-subgraph-studio/  permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/studio/transferring-subgraph-ownership/$      $scheme://$http_host/docs/$1/subgraphs/developing/managing/transferring-a-subgraph/ permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/subgraphs/$                                   $scheme://$http_host/docs/$1/subgraphs/developing/subgraphs/                        permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/substreams/$                                  $scheme://$http_host/docs/$1/substreams/introduction/                               permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/substreams/developing/sinks/sinks/$           $scheme://$http_host/docs/$1/substreams/developing/sinks/                           permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/sunrise/$                                     $scheme://$http_host/docs/$1/archived/sunrise/                                      permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/supported-network-requirements/$              $scheme://$http_host/docs/$1/indexing/supported-network-requirements/               permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/supported-networks/arweave/$                  $scheme://$http_host/docs/$1/subgraphs/cookbook/arweave/                            permanent;