From 8f299b8c49aa0a9ac996406793a4b18baca37c11 Mon Sep 17 00:00:00 2001 From: jwortmann Date: Fri, 26 Jan 2024 22:50:18 +0100 Subject: [PATCH] A few enhancements for the docs website (#2402) --- docs/mkdocs.yml | 27 +++-- docs/src/client_configuration.md | 2 +- docs/src/commands.md | 24 ++--- docs/src/customization.md | 15 +-- docs/src/features.md | 16 ++- docs/src/images/favicon.svg | 172 +++++++++++++++++++++++++++++++ docs/src/images/logo.svg | 6 ++ 7 files changed, 218 insertions(+), 44 deletions(-) create mode 100644 docs/src/images/favicon.svg create mode 100644 docs/src/images/logo.svg diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 3c963200f..53783ba14 100644 --- a/docs/mkdocs.yml +++ b/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: diff --git a/docs/src/client_configuration.md b/docs/src/client_configuration.md index c75c5ce9a..8b01dd573 100644 --- a/docs/src/client_configuration.md +++ b/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, diff --git a/docs/src/commands.md b/docs/src/commands.md index ebb7d0a65..800c082ba 100644 --- a/docs/src/commands.md +++ b/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) | diff --git a/docs/src/customization.md b/docs/src/customization.md index 234837dab..e0f635c6d 100644 --- a/docs/src/customization.md +++ b/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 ctrl+left click: -```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 diff --git a/docs/src/features.md b/docs/src/features.md index f673c23bd..67d156aca 100644 --- a/docs/src/features.md +++ b/docs/src/features.md @@ -152,15 +152,13 @@ This package presents Code Lenses as a greenish clickable annotation positioned Sublime Text has no concept of Code Lenses. -
- ![code-lens](./images/code-lens-annotation.png) -
"show_code_lens" is set to "annotation"
-
+=== ""show_code_lens": "annotation"" -
- ![code-lens](./images/code-lens-phantom.png) -
"show_code_lens" is set to "phantom"
-
+ ![code-lens](./images/code-lens-annotation.png) + +=== ""show_code_lens": "phantom"" + + ![code-lens](./images/code-lens-phantom.png) ## Inlay Hints @@ -168,7 +166,7 @@ Inlay hints are short textual annotations that show parameter names and type hin ![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." diff --git a/docs/src/images/favicon.svg b/docs/src/images/favicon.svg new file mode 100644 index 000000000..9dabbf7b3 --- /dev/null +++ b/docs/src/images/favicon.svg @@ -0,0 +1,172 @@ + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + diff --git a/docs/src/images/logo.svg b/docs/src/images/logo.svg new file mode 100644 index 000000000..b78fd2296 --- /dev/null +++ b/docs/src/images/logo.svg @@ -0,0 +1,6 @@ + + + + + +