Docs improvements, site fixes

docs/guide/collections.md

@@ -7,10 +7,42 @@ It contains no "special files" or metadata -- it's just a directory.
 It could even be empty.
 "Collection" is simply the name we give to the directory which we've loaded into Posting.
 
+## The collection browser
+
+Posting displays the currently open collection in the sidebar.
+This is called the *collection browser*.
+
+![Posting collection tree](../assets/collection-tree.png){ height=300px }
+
+The name of the currently open collection is displayed in the bottom right corner of the collection browser.
+In the example above, the collection is named "sample-collection".
+
+You can navigate this sidebar using the keyboard or mouse.
+Open a request by clicking on it or pressing ++enter++ while it has focus,
+and it'll be loaded into the main body of the UI.
+A marker will also appear to the left of the request's title, indicating that the request is open.
+A save operation will overwrite the currently open request.
+
+!!! example "Keyboard shortcuts"
+
+    The collection browser supports various keyboard shortcuts for quick navigation. For example ++shift+j++ and ++shift+k++ can be used to jump through sub-collections.
+    Press ++f1++ while the browser has focus to view the full list of shortcuts.
+
+
+The collection browser can be moved to the left or right side of the screen by setting the `collection_browser.position` configuration option
+to either `"left"` or `"right"`.
+
 ## The default collection
 
-If you launch Posting without any arguments, it will load the *default collection*, which is stored in Posting's reserved data directory on your file system.
+If you launch Posting without a `--collection` argument, it will load the *default collection*, which is stored in Posting's reserved data directory on your file system.
+
+The default collection can be thought of as a *system wide collection*.
+It's a place to keep useful requests that you can easily access from anywhere, without having to manually specify a `--collection` argument.
+
 You can check where this is by running `posting locate collection`.
+The default collection is named "default", that name will be displayed in the bottom right corner of the collection browser.
+
+![Posting default collection](../assets/default-collection.png)
 
 This is useful to get started quickly, but you'll probably want to create your own collection directory and load it instead.
 This makes it easier to organize your requests and check them into version control.
@@ -19,6 +51,8 @@ This makes it easier to organize your requests and check them into version contr
 
 A collection is just a directory, so you can create a collection by simply creating an empty directory anywhere on your file system.
 
+With the directory created, it's time to load it into Posting...
+
 ## Loading a collection
 
 If you want to load a collection, you can do so by passing the path to the collection directory to Posting:
@@ -27,9 +61,7 @@ If you want to load a collection, you can do so by passing the path to the colle
 posting --collection path/to/collection
 ```
 
-## Example
-
-
+### Example
 
 To open a collection (a directory containing requests), use the `--collection` option:
 
@@ -39,4 +71,4 @@ posting --collection path/to/collection
 
 This will recursively find and display requests in the sidebar.
 If you don't supply a directory, Posting will use the default collection directory.
-You can check where this is by running `posting locate collection`.
+You can check where the default collection is by running `posting locate collection`.

docs/guide/index.md

@@ -7,6 +7,10 @@ It's significantly faster than alternative tools, and will get you up and runnin
 
 You don't even need to worry about installing Python yourself - `uv` will manage everything for you.
 
+### uv
+
+Here's how to install Posting using `uv`:
+
 ```bash
 # quick install on MacOS/Linux
 curl -LsSf https://astral.sh/uv/install.sh | sh
@@ -19,11 +23,6 @@ uv tool install --python 3.12 posting
 
 `uv` also makes it easy to install additional Python packages into your Posting environment, which you can then use in your pre-request/post-response scripts.
 
-### Prefer `pipx`?
-
-If you'd prefer to use `pipx`, that works too: `pipx install posting`.
-
-
 ### pipx
 
 If you prefer, you can install Posting via [`pipx`](https://pipx.pypa.io/stable/).
@@ -57,12 +56,13 @@ This introduction will show you how to create a simple POST request to the [JSON
 
 A *collection* is simply a directory which may contain requests saved by Posting.
 
-If you launch Posting without specifying a collection, any requests you create will be saved in the `"default"` collection.
-This is a directory reserved by Posting on your filesystem, and unrelated to the directory you launched Posting from.
+If you launch Posting without specifying a collection, any requests you create will be saved to the `"default"` collection.
+
+The default collection is a directory reserved by Posting on your filesystem. It's a "global" collection and is not related to the directory you launched Posting from.
 
 This is fine for quick throwaway requests, but you'll probably want to create a new collection for each project you work on so that you can check it into version control.
 
-To create a new collection, simply create a new directory and pass it into Posting:
+To create a new collection, simply create a new directory and pass it into Posting.
 
 ```bash
 mkdir my-collection
@@ -71,21 +71,46 @@ posting --collection my-collection
 
 Now, any requests you create will be saved in the `my-collection` directory as simple YAML files with the `.posting.yaml` extension.
 
-### Creating a request
+When Posting opens, you'll see the collection browser on the left side of the screen with `my-collection` displayed at the bottom right corner.
+
+### Setting the request method to POST
 
 When you launch Posting, no request is open, so the UI will look rather empty.
 
 Let's create a simple POST request to the [JSONPlaceholder](https://jsonplaceholder.typicode.com/) mock API to create a new user.
 
-Press ++ctrl+t++ to open the request method dropdown, then press ++p++ to quickly select the `POST` method.
+Press ++ctrl+t++ to open the request method dropdown:
+
+![Posting request method dropdown](../assets/request-method-dropdown.png)
+
+The underlined character in each method indicates the key you can press to quickly select that method. We want to send a POST request, so press ++p++ to quickly select the POST method.
+
+### Setting the request URL
 
-Press ++tab++ to move focus to the next widget, which is the URL bar. The URL bar can also be focused with ++ctrl+l++. Type `https://jsonplaceholder.typicode.com/users` into the URL bar.
+You can move focus forward and backward through widgets using ++tab++ and ++shift+tab++ respectively.
+So, you can move focus from the method selector to the URL bar by pressing ++tab++ once.
+
+Alternatively, you can immediately move the focus to the URL bar from anywhere in Posting using ++ctrl+l++.
+
+Type `https://jsonplaceholder.typicode.com/users` into the URL bar.
+
+![Posting URL bar](../assets/url-bar.png)
+
+Posting's URL bar highlights parts of the URL as you type, which can be helpful for spotting typos.
+
+It can also autocomplete domains you've previously used, to save you from having to retype them.
+For example, if you later want to make a request to `https://jsonplaceholder.typicode.com/posts`, you can simply type "json" into the URL bar and select the URL from the autocomplete menu that appears.
+
+![Posting URL autocomplete](../assets/url-autocomplete.gif)
 
 ### Adding a JSON body
 
 Press ++ctrl+o++ to enter "jump mode", then press ++w++ to quickly jump to the "Body" tab.
+Jump mode is great for quickly moving through the UI without having to press ++tab++ multiple times.
 
-Press ++j++ (or ++down++) to move the cursor down to the dropdown. Press ++enter++ to open it, and select the option `Raw (json, text, etc.)`.
+At this point focus is currently on the tab bar itself.
+Press ++j++ (or ++down++) to move the cursor down to the dropdown.
+Press ++enter++ to open it, then select the option `Raw (json, text, etc.)`.
 
 Move down to the text area below using ++j++ (or ++down++), and type (or paste) the JSON below. 
 
@@ -97,14 +122,26 @@ Move down to the text area below using ++j++ (or ++down++), and type (or paste)
 }
 ```
 
+Note at the bottom right of the text area, JSON is pre-selected as the content type.
+This means Posting will automatically use JSON syntax highlighting and it will insert the `Content-Type: application/json` header for you when the request is sent.
+
 ### Viewing keyboard shortcuts
 
 Now is probably a good time to note that you can see the full list of keyboard shortcuts for the focused widget by pressing ++f1++. The text area widget in particular has a lot of useful shortcuts and supports things like undo/redo.
 
+!!! tip "Changing keyboard shortcuts"
+
+    You can remap keybindings in Posting using [Keymaps](../guide/keymap.md).
 
 ### Sending the request
 
-Press ++ctrl+j++ to send the request. This shortcut works globally.
+Press ++ctrl+j++ to send the request.
+This shortcut works globally.
+
+!!! tip "Keyboard shortcuts"
+
+    You may also be able to send the request using ++alt+enter++.
+    This only works on terminals that support the Kitty graphics protocol.
 
 ### Saving the request
 

docs/guide/keymap.md

@@ -1,8 +1,9 @@
 ## Overview
 
-As explained in the [Help System](./help_system.md) section, you can view the keybindings for any widget by pressing `F1` or `?` when that widget has focus.
+As explained in the [Help System](./help_system.md) section, you can view the keybindings for any widget by pressing ++f1++ or ++ctrl+question-mark++ when that widget has focus.
 
 If you wish to use different keybindings, you can do so by editing the `keymap` section of your `config.yaml` file.
+Check the location of that file on your system by running `posting locate config` on the command line.
 
 ### Changing the keymap
 

docs/guide/navigation.md

@@ -24,6 +24,15 @@ You can check these by pressing <kbd>f1</kbd> while it is focused.
 
 Where it makes sense, <kbd>up</kbd> and <kbd>down</kbd> will also move between widgets.
 
+## Mouse navigation
+
+You can also navigate Posting entirely using the mouse, very much like a typical GUI application.
+
+If a widget shows a scrollbar, you can use the mouse wheel or trackpad gestures to scroll through its content.
+Scrollbars can also be clicked and dragged.
+
+If you hold shift and scroll using the trackpad or mousewheel, the content will scroll horizontally (if there's a horizontal scrollbar).
+
 ## Contextual help
 
 Many widgets have additional bindings for navigation other than those displayed in the footer. You can view the full list of keybindings for the currently
@@ -37,6 +46,7 @@ You can use the `focus.on_startup` and `focus.on_response` configuration options
 |----------------------|---------------|-------------|
 | `focus.on_startup` | `"url"`, `"method", "collection"` (Default: `"url"`) | Automatically focus the URL bar, method, or collection browser when the app starts. |
 | `focus.on_response` | `"body"`, `"tabs"` (Default: `unset`)| Automatically focus the response tabs or response body text area when a response is received. |
+| `focus.on_request_open` | `"headers"`, `"body"`, `"query"`, `"info"`, `"url"`, `"method"` (Default: `unset`) | Automatically focus the specified target when a request is opened from the collection browser. |
 
 ## Exiting
 

docs/overrides/home.html

@@ -5,11 +5,6 @@
     /* hide the main content on the home page.
     we're gonna do it all ourself. */
     html { scroll-behavior: smooth; }
-    .md-main{
-        display: none;
-      max-width: 1000px;
-      margin: 0 auto;
-    }
     body {
         background-image: linear-gradient(
             0deg,
@@ -54,9 +49,14 @@
     #home-title {
       margin: 0 0 0.3rem 0;
     }
+    }
     p#home-intro {
       font-size: 0.9rem;
     }
+
+    div.md-nav__source {
+        background-color: hsla(287deg, 100%, 10%, 0.8) !important;
+    }
     #home-subtitle {
       font-family: "Roboto Mono", monospace;
       font-size: 1rem;
@@ -253,6 +253,16 @@
         }
     }
 
+    @media (min-width: 1220px) {
+        /* The sidebar content sits on top of the main content
+        and makes some buttons unclickable. This is a hack to workaround
+        that while keeping the sidebar working on screensizes where it's
+        still required.*/
+        body > div.md-container > main > div {
+            display: none;
+        }
+    }
+
     @media (min-width: 1080px) {
         .feature-description {
             font-size: 1rem;

docs/stylesheets/extra.css

@@ -33,6 +33,12 @@ table {
     border: 1px solid hsl(287deg 100% 30%) !important;
 }
 
+span.filename {
+    background: hsla(287deg, 100%, 10%, 0.4) !important;
+    border: 1px solid hsl(287deg 100% 30%) !important;
+    border-bottom: none !important;
+    color: hsla(286, 42%, 73%, 0.526) !important;
+}
 
 .md-nav__link {
     background-color: transparent !important;
@@ -105,6 +111,7 @@ nav.md-tabs {
 }
 .md-content {
     background-color: rgba(0,0,0,0);
+    padding-bottom: 2.5rem;
 }
 .md-nav__title {
     box-shadow: none !important;

mkdocs.yml

@@ -27,8 +27,8 @@ nav:
   - Guide:
     - "Getting Started": "guide/index.md"
     - "Navigation": "guide/navigation.md"
-    - "Requests": "guide/requests.md"
     - "Collections": "guide/collections.md"
+    - "Requests": "guide/requests.md"
     - "Configuration": "guide/configuration.md"
     - "Environments": "guide/environments.md"
     - "Command Palette": "guide/command_palette.md"

tests/sample-collections/foo.posting.yaml

@@ -0,0 +1 @@
+name: foo