A few enhancements for the docs website (#2402)

docs/mkdocs.yml

@@ -17,9 +17,12 @@ theme:
     scheme: slate
     accent: orange
     primary: orange
-
-  icon:
-    logo: fontawesome/solid/book-open
+  logo: images/logo.svg
+  favicon: images/favicon.svg
+  features:
+    - content.code.copy
+    - content.tooltips
+    - navigation.top
 
 # override css
 extra_css:
@@ -38,6 +41,8 @@ markdown_extensions:
         - name: jsonc
           lang: json
   - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
 
   # add tip, warning info boxes
   - admonition
@@ -49,14 +54,14 @@ markdown_extensions:
       permalink: '#'
 
 nav:
-    - Getting Started: index.md
-    - Language Servers: language_servers.md
-    - Features: features.md
-    - Commands: commands.md
-    - Keyboard Shortcuts: keyboard_shortcuts.md
-    - Customization: customization.md
-    - Client Configuration: client_configuration.md
-    - Troubleshooting: troubleshooting.md
+  - Getting Started: index.md
+  - Language Servers: language_servers.md
+  - Features: features.md
+  - Commands: commands.md
+  - Keyboard Shortcuts: keyboard_shortcuts.md
+  - Customization: customization.md
+  - Client Configuration: client_configuration.md
+  - Troubleshooting: troubleshooting.md
 
 extra:
   social:

docs/src/client_configuration.md

@@ -14,7 +14,7 @@ If your language server is missing or not configured correctly, you need to add/
 
 Below is an example of the `LSP.sublime-settings` file with configurations for the [Phpactor](https://phpactor.readthedocs.io/en/master/usage/language-server.html#language-server) server.
 
-```jsonc
+```jsonc title="Packages/User/LSP.sublime-settings"
 {
   // General settings
   "show_diagnostics_panel_on_save": 0,

docs/src/commands.md

@@ -19,7 +19,7 @@ For LSP servers that can handle [workspace/executeCommand](https://microsoft.git
 
 Example:
 
-```jsonc
+```jsonc title="Packages/User/Default.sublime-commands"
 [
   // ...
   {
@@ -43,14 +43,14 @@ You can include special variables in the `command_args` array that will be autom
 
 | Variable | Type | Description |
 | -------- | ---- | ----------- |
-| `"$document_id"` or `"${document_id}"` | object | JSON object `{ 'uri': string }` containing the file URI of the active view, see [Document Identifier](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier) |
-| `"$file_uri"` or `"${file_uri}"` | string | File URI of the active view |
-| `"$selection"` or `"${selection}"` | string | Content of the (topmost) selection |
-| `"$offset"` or `"${offset}"` | int | Character offset of the (topmost) cursor position |
-| `"$selection_begin"` or `"${selection_begin}"` | int | Character offset of the begin of the (topmost) selection |
-| `"$selection_end"` or `"${selection_end}"` | int | Character offset of the end of the (topmost) selection |
-| `"$position"` or `"${position}"` | object | JSON object `{ 'line': int, 'character': int }` of the (topmost) cursor position, see [Position](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#position) |
-| `"$line"` or `"${line}"` | int | Zero-based line number of the (topmost) cursor position, see [Position](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#position) |
-| `"$character"` or `"${character}"` | int | Zero-based character offset relative to the current line of the (topmost) cursor position, see [Position](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#position) |
-| `"$range"` or `"${range}"` | object | JSON object with `'start'` and `'end'` positions of the (topmost) selection, see [Range](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#range) |
-| `"$text_document_position"` or `"${text_document_position}"` | object | JSON object with `'textDocument'` and `'position'` of the (topmost) selection, see [TextDocumentPositionParams](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams) |
+| `"$document_id"` | object | JSON object `{ 'uri': string }` containing the file URI of the active view, see [Document Identifier](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier) |
+| `"$file_uri"` | string | File URI of the active view |
+| `"$selection"` | string | Content of the (topmost) selection |
+| `"$offset"` | int | Character offset of the (topmost) cursor position |
+| `"$selection_begin"` | int | Character offset of the begin of the (topmost) selection |
+| `"$selection_end"` | int | Character offset of the end of the (topmost) selection |
+| `"$position"` | object | JSON object `{ 'line': int, 'character': int }` of the (topmost) cursor position, see [Position](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#position) |
+| `"$line"` | int | Zero-based line number of the (topmost) cursor position, see [Position](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#position) |
+| `"$character"` | int | Zero-based character offset relative to the current line of the (topmost) cursor position, see [Position](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#position) |
+| `"$range"` | object | JSON object with `'start'` and `'end'` positions of the (topmost) selection, see [Range](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#range) |
+| `"$text_document_position"` | object | JSON object with `'textDocument'` and `'position'` of the (topmost) selection, see [TextDocumentPositionParams](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams) |

docs/src/customization.md

@@ -4,7 +4,7 @@ LSP's key bindings can be edited from the `Preferences: LSP Key Bindings` comman
 
 If you want to create a new key binding that is different from the ones that are already included, you might want to make it active only when there is a language server with a specific [LSP capability](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#initialize) (refer to the `ServerCapabilities` structure in that link) running. In that case, you can make use of the `lsp.session_with_capability` context. For example, the following key binding overrides `ctrl+r` to use LSP's symbol provider but only when the current view has a language server with the `documentSymbolProvider` capability and we're in a javascript or a typescript file:
 
-```jsonc
+```jsonc title="Packages/User/Default.sublime-keymap"
 {
     "command": "lsp_document_symbols",
     "keys": [
@@ -29,17 +29,11 @@ Generally, you should not need to restrict your key bindings to specific scopes
 
 ## Mouse map configuration
 
-If you want to bind some action to a mouse, open `Preferences / Browse Packages` from the main menu and create a sublime-mousemap file in the following location within the Packages folder:
-
-| Platform | Path |
-| -------- | ---- |
-| Windows  | `/User/Default (Windows).sublime-mousemap` |
-| Linux    | `/User/Default (Linux).sublime-mousemap` |
-| Mac      | `/User/Default (OSX).sublime-mousemap` |
+If you want to bind some action to a mouse, select `Preferences / Mouse Bindings` from the main menu and edit the file on the righthand side.
 
 Here is an example of a mouse binding that triggers LSP's "go to symbol definition" command on pressing the <kbd>ctrl</kbd>+<kbd>left click</kbd>:
 
-```jsonc
+```jsonc title="Packages/User/Default.sublime-mousemap"
 [
     {
         "button": "button1",
@@ -57,13 +51,12 @@ LSP uses [mdpopups](https://github.com/facelessuser/sublime-markdown-popups) to
 You can override its style by creating a `Packages/User/mdpopups.css` file.
 In particular, to get the same font in the popup as your `"font_face"` setting in `Packages/User/Preferences.sublime-settings`, add
 
-```css
+```css title="Packages/User/mdpopups.css"
 html {
     --mdpopups-font-mono: "your desired font face";
 }
 ```
 
-to `Packages/User/mdpopups.css`.
 See the [mdpopups documentation](http://facelessuser.github.io/sublime-markdown-popups/) for more details.
 
 ## Inlay Hints

docs/src/features.md

@@ -152,23 +152,21 @@ This package presents Code Lenses as a greenish clickable annotation positioned
 
 Sublime Text has no concept of Code Lenses.
 
-<figure markdown>
-  ![code-lens](./images/code-lens-annotation.png)
-  <figcaption>"show_code_lens" is set to "annotation"</figcaption>
-</figure>
+=== ""show_code_lens": "annotation""
 
-<figure markdown>
-  ![code-lens](./images/code-lens-phantom.png)
-  <figcaption>"show_code_lens" is set to "phantom"</figcaption>
-</figure>
+    ![code-lens](./images/code-lens-annotation.png)
+
+=== ""show_code_lens": "phantom""
+
+    ![code-lens](./images/code-lens-phantom.png)
 
 ## Inlay Hints
 
 Inlay hints are short textual annotations that show parameter names and type hints for servers that support that feature.
 
 ![inlay-hints](./images/inlay-hints.png)
 
-To enable inlay hints, enable the `show_inlay_hints` setting through `Preferences: LSP Settings`.
+Inlay hints are disabled by default and can be enabled with the `"show_inlay_hints": true` setting through `Preferences: LSP Settings`.
 
 !!! info "Some servers require additional settings to be enabled in order to show inlay hints."