docs: add a page about the inbox

apps/webapp/src/routes/dashboard.tsx

@@ -24,8 +24,8 @@ export default function Dashboard() {
             setNewSection({
                 label: searchParams.get("label") || "",
                 search: searchParams.get("search") || "",
-                notified: false,
-                attention: true,
+                notified: defaultSectionProps.notified,
+                attention: defaultSectionProps.attention,
             })
             setEditing(true)
         }

apps/website/astro.config.mjs

@@ -20,7 +20,6 @@ export default defineConfig({
       social: {
         github: "https://github.com/pvcnt/mergeable",
       },
-      pagination: false,
       sidebar: [
         {
           label: "About",

apps/website/src/content/docs/about/index.md

@@ -10,7 +10,7 @@ Switching between tabs is slow, and there is no way to see all pull requests fro
 
 Mergeable is a better inbox for GitHub pull requests, that displays all pull requests of interest on a single page in a very flexible manner:
 
-![Inbox](/mergeable/images/inbox.png)
+![Inbox](../../../assets/screenshots/dashboard.png)
 
 ## Compare with...
 

apps/website/src/content/docs/self-host/static-files.mdx → apps/website/src/content/docs/self-host/static-files.md

@@ -20,9 +20,9 @@ pnpm build
 This will create a static website under the `apps/webapp/dist` directory.
 The content of this directory can then be dropped into your Web server of hosting platform.
 
-<Aside type="caution">
+:::caution
 The Web server or hosting platform must be configured so that all traffic directed to a path that does not match an existing file should be redirected to `index.html`.
-</Aside>
+:::
 
 ## Configuration
 

apps/website/src/content/docs/user-guide/connections.md

@@ -4,3 +4,6 @@ draft: true
 sidebar:
   order: 4
 ---
+
+For now, Mergeable has only been tested with classic access tokens.
+Make sure to select at least the `read:org`, `repo` and `user` scopes.

apps/website/src/content/docs/user-guide/inbox.md

@@ -1,6 +1,83 @@
 ---
 title: Use the inbox
-draft: true
 sidebar:
   order: 2
 ---
+
+The landing page of Mergeable is its inbox, that shows all pull requests in your radar.
+
+## Dashboard sections
+
+The dashboard displays a list of sections, each of them being defined as a search query against pull requests.
+By default, some default sections are populated:
+
+![Dashboard sections](../../../assets/screenshots/dashboard-empty.png)
+
+But those are only created for your convenience, as they can all be modified or even replaced.
+
+### Add a new section
+
+You can add a new section at the bottom by clicking on the "New section" button in the header.
+The following dialog will open:
+
+![New section dialog](../../../assets/screenshots/new-section.png)
+
+You need to provide a label and a search query.
+The search query uses [GitHub's search language for pull requests](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests), with the following modifications:
+
+* A `type:pr` term is implicitely added, you do not need to include it.
+* Pull requests are always sorted by last updated first (i.e., `sort:updated`).
+* Archived pull requests are excluded by default (i.e., `archived:false`), unless the search query is explicitely searching for archived pull requests.
+* Only pull requests from organizations configured in the connection are returned.
+* You may provide several individual search queries separated by a semi-colon (";").
+Results from all individual search queries will be merged and displayed together in the section.
+
+### Edit a section
+
+You may edit an existing section by clicking on the pencil icon on the right side, next to its label.
+
+### Move sections
+
+You may move an existing section by clicking on the up or down arrows on the right side, next to its label.
+One of the arrows may be greyed, indicating that the section is already at the top or bottom of the dashboard.
+
+### Share a section
+
+You may share the configuration of a section by clicking on the pencil icon, and then at the bottom on the dialog on "Share".
+This will copy a URL in your clipboard, that you can then share with your teammates.
+Openining it in the browser will direct them to their own dashboard, with a new section dialog open and pre-populated with parameters associated with the section you shared.
+
+## Search for pull requests
+
+You may search for pull requests using the command bar, that is invoked by <code>cmd+k</code>:
+
+![Command bar](../../../assets/screenshots/search-pulls.png)
+
+This performs a fuzzy search on the title, and highlights the matching characters.
+Clicking on a pull requests (or using keyboard arrows and hitting enter) will open the selected pull request in a new tab.
+
+You may search for any pull request that is synchronized in Mergeable, i.e., any pull request that appears on the dashboard.
+This does not allow to search for random pull requests on GitHub.
+
+## Star pull requests
+
+When you have too many pull requests on your dashboard, it may become difficult to identify those that require a particular attention.
+Starring a pull request allows to bookmark it and make it stand apart from other pull requests.
+
+You may (un)star a pull request by clicking on the star icon in the dashboard.
+Once a pull request is starred, the star will appeared filled in the dashboard.
+Starred pull requests appear in the "Starred pulls" tab of the inbox.
+
+## Synchronize pull requests
+
+Pull requests are automatically synchronized in the background every 5 minutes.
+You may forcefully synchronize them by clicking on the refresh button in the sidebar.
+Hovering over it displays the time at which pull requests were last synchronized:
+
+![Refresh button with tooltip](../../../assets/screenshots/refresh-button.png)
+
+:::note
+Every synchronization has a cost in terms of API usage.
+Indeed, GitHub API has limits in terms of how many requests may be performed per hour ([REST limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api), [GraphQL limits](https://docs.github.com/en/graphql/overview/rate-limits-and-node-limits-for-the-graphql-api)).
+Please remember that other tools using a personal access token (or OAuth login) associated with a same account will also consume the same quota.
+:::

apps/website/src/content/docs/user-guide/index.md

@@ -7,23 +7,18 @@ sidebar:
 The fastest way to get started is to use the public instance of Mergeable available at [mergeable.pages.dev](https://mergeable.pages.dev).
 This instance is provided free of charge, and allows to interact with pull requests from [github.com](https://github.com), from public and private repositories alike.
 
-## Connect to github.com
+:::note
+If you need to interact with a private GitHub Enterprise instance, please consider [self-hosting](../self-host).
+:::
 
 When you first start Mergeable, it displays an empty dashboard, because it is not connected to any GitHub instance.
 From [the Settings page](https://mergeable.pages.dev/settings), accessible via the sidebar, click on the "New connection" button.
-You should end up with the following dialog:
+The following dialog will open:
 
-![New connection dialog](/mergeable/images/new-connection.png)
+![New connection dialog](../../../assets/screenshots/new-connection.png)
 
 You only have to provide an access token, that you can [obtain from GitHub](https://github.com/settings/tokens).
-For now, Mergeable has only been tested with classic access tokens.
-Make sure to select at least the `read:org`, `repo` and `user` scopes.
 Copy and paste the access token in the dialog, and click on "Submit".
+After going back to [the Inbox page](https://mergeable.pages.dev/inbox), you may already see some reviews in the dashboard if you are an active GitHub user:
 
-Going back to [the Inbox page](https://mergeable.pages.dev/inbox), you may already see some reviews in the dashboard if you are an active GitHub user:
-
-![Inbox](/mergeable/images/inbox.png)
-
-## Connect to GitHub Enterprise
-
-If you need to interact with a private GitHub Enterprise instance, please consider [self-hosting](../self-host).
+![Inbox](../../../assets/screenshots/dashboard.png)