Consolidate docs to Jekyll site

.github/ISSUE_TEMPLATE/bug_template_non_vscode.yml

@@ -13,7 +13,7 @@ body:
         Please note that the maintainers only have bandwidth to prioritize VS Code support and lean on the community to assist with supporting other editors.
         If you are using a non-VS Code editor, please follow these steps **before submitting a bug report**:
 
-        1. Follow the instructions on [troubleshooting](https://github.com/Shopify/ruby-lsp/blob/main/TROUBLESHOOTING.md)
+        1. Follow the instructions on [troubleshooting](https://shopify.github.io/ruby-lsp/troubleshooting.html)
         2. Check if the editor and LSP plugin you use are up to date, and if they support the latest [Language Server Protocol Specification](https://microsoft.github.io/language-server-protocol).
         3. Seek help in the [Ruby DX Slack](https://join.slack.com/t/ruby-dx/shared_invite/zt-2c8zjlir6-uUDJl8oIwcen_FS_aA~b6Q).
         4. Seek help in the related editor/plugin's issue tracker.

.github/ISSUE_TEMPLATE/bug_template_vscode.yml

@@ -13,7 +13,7 @@ body:
         ### Before submitting
 
         Please follow the instructions on
-        [troubleshooting](https://github.com/Shopify/ruby-lsp/blob/main/TROUBLESHOOTING.md) and make sure you
+        [troubleshooting](https://shopify.github.io/ruby-lsp/troubleshooting.html) and make sure you
         are:
         1. On the latest version of the Ruby LSP VS Code extension
         2. On the latest version of the Ruby LSP server gem
@@ -23,7 +23,7 @@ body:
 
         Please run the `Collect Ruby LSP Information for Issue Reporting` command through VS Code's command
         palette and paste the result below.
-        
+
   - type: textarea
     attributes:
       label: Description
@@ -32,7 +32,7 @@ body:
         ### Ruby LSP Information
 
         <!-- Please run `Collect Ruby LSP Information for Issue Reporting` from VS Code's command palette and paste the result here -->
-        
+
         ### Reproduction steps
 
         <!-- Suggested structure -->

.github/workflows/publish.yml

@@ -123,7 +123,6 @@ jobs:
       - name: Copy files needed for release
         run: |
           cp CODE_OF_CONDUCT.md vscode/CODE_OF_CONDUCT.md
-          cp TROUBLESHOOTING.md vscode/TROUBLESHOOTING.md
 
       - name: 📦 Install dependencies
         working-directory: ./vscode

README.md

@@ -19,7 +19,7 @@ Want to discuss Ruby developer experience? Consider joining the public
 
 For VS Code users, you can start by installing the [Ruby LSP extension](https://marketplace.visualstudio.com/items?itemName=Shopify.ruby-lsp) from the VS Code marketplace.
 
-For other editors, please refer to the [EDITORS](https://github.com/Shopify/ruby-lsp/blob/main/EDITORS.md) guide.
+For other editors, please refer to the [EDITORS](https://shopify.github.io/ruby-lsp/editors.html) guide.
 
 To learn more about Ruby LSP, please refer to the official [documentation](https://shopify.github.io/ruby-lsp) for [supported features](https://shopify.github.io/ruby-lsp#features).
 

ADDONS.md → jekyll/addons.markdown

@@ -1,9 +1,16 @@
-# Ruby LSP addons
+---
+layout: default
+title: Addons
+nav_order: 10
+parent: Ruby LSP
+---
 
-> [!WARNING]
+# Addons
+
+{: .warning }
 > The Ruby LSP addon system is currently experimental and subject to changes in the API
 
-Need help writing addons? Consider joining the #ruby-lsp-addons channel in the [Ruby DX Slack
+Need help writing addons? Consider joining the `#ruby-lsp-addons` channel in the [Ruby DX Slack
 workspace](https://join.slack.com/t/ruby-dx/shared_invite/zt-2c8zjlir6-uUDJl8oIwcen_FS_aA~b6Q).
 
 ## Motivation and goals

DESIGN_AND_ROADMAP.md → jekyll/design-and-roadmap.markdown

@@ -1,3 +1,10 @@
+---
+layout: default
+title: Design and roadmap
+nav_order: 20
+parent: Ruby LSP
+---
+
 # Ruby LSP design and roadmap
 
 - [Design principles](#design-principles)
@@ -67,7 +74,7 @@ If you require more accuracy in your editor, consider adopting a type system and
 This applies to multiple language server features such as go to definition, hover, completion and automated refactors.
 Consider the following examples:
 
-> [!NOTE]
+{: .note }
 > Not all of the examples below are supported at the moment and this is not an exhaustive list.
 > Please check the long term roadmap to see what’s planned
 
@@ -143,7 +150,7 @@ We believe that a less fragmented tooling ecosystem leads to a better user exper
 and consolidates efforts from the community.
 
 Our goal is to allow the Ruby LSP to connect to different formatters, linters, type checkers or even extract runtime
-information from running applications like Rails servers. You can learn more in the [addons documentation](ADDONS.md).
+information from running applications like Rails servers. You can learn more in the [addons documentation](addons).
 
 ### Relying on Bundler
 
@@ -234,7 +241,7 @@ user.name
 @post.like!
 ```
 
-> [!IMPORTANT]
+{: .important }
 > The goal of this experiment is to understand if we can get better accuracy for the code that you already
 > have. The hypothesis is that a reasonable amount of code already uses patterns like the ones in the example and, in
 > those cases, we can achieve nicer results.

EDITORS.md → jekyll/editors.markdown

@@ -1,20 +1,26 @@
+---
+layout: default
+title: Editors
+nav_order: 0
+parent: Ruby LSP
+---
+
 # Editors
 
 This file contains community driven instructions on how to set up the Ruby LSP in editors other than VS Code. For VS
 Code, use the official [Ruby LSP extension](https://marketplace.visualstudio.com/items?itemName=Shopify.ruby-lsp).
 
-> [!NOTE]
+{: .note }
 > Some Ruby LSP features may be unavailable or limited due to incomplete implementations of the Language Server
 > Protocol, such as dynamic feature registration, or [file watching](https://github.com/Shopify/ruby-lsp/issues/1456).
 
 If you need to select particular features to enable or disable, see
 [`vscode/package.json`](vscode/package.json) for the full list.
 
-**IMPORTANT NOTE FOR ALL EDITORS**
-
-The command to launch the language server might depend on which editor and version manager combination you are using.
-In order to work properly, the Ruby LSP must be launched with the Ruby version being used by the project you are working
-on and with the correct Bundler environment set.
+{: .important }
+> The command to launch the language server might depend on which editor and version manager combination you are using.
+> In order to work properly, the Ruby LSP must be launched with the Ruby version being used by the project you are working
+> on and with the correct Bundler environment set.
 
 If you normally launch your editor from the terminal in a shell session where the Ruby environment is already activated,
 then you can probably just use `ruby-lsp` as the command.

jekyll/index.markdown

@@ -48,7 +48,7 @@ For more information on using and configuring the extension, see the extension's
 
 ### With other editors
 
-See [editors](https://github.com/Shopify/ruby-lsp/blob/main/EDITORS.md) for community instructions on setting up the Ruby LSP, which current includes Emacs, Neovim, Sublime Text, and Zed.
+See [editors](editors) for community instructions on setting up the Ruby LSP, which current includes Emacs, Neovim, Sublime Text, and Zed.
 
 The gem can be installed by doing
 
@@ -75,7 +75,7 @@ Additionally, some tools may include a Ruby LSP addon directly, like
 Other community driven addons can be found in [rubygems](https://rubygems.org/search?query=name%3A+ruby-lsp) by
 searching for the `ruby-lsp` prefix.
 
-For instructions on how to create addons, see the [addons documentation](https://github.com/Shopify/ruby-lsp/blob/main/ADDONS.md).
+For instructions on how to create addons, see the [addons documentation](addons).
 
 ## Features
 
@@ -189,7 +189,7 @@ By guessing the types of variables, Ruby LSP can expand the code navigation feat
 - Identifiers are not ideal for complex type annotations and can be easily misled by non-matching names.
 - We do NOT recommend renaming identifiers just to make this feature work.
 
-For more information, please refer to the [documentation](https://github.com/Shopify/ruby-lsp/blob/main/DESIGN_AND_ROADMAP.md#guessed-types).
+For more information, please refer to the [documentation](https://shopify.github.io/ruby-lsp/design-and-roadmap.html#guessed-types).
 
 ## Configuration
 

SEMANTIC_HIGHLIGHTING.md → jekyll/semantic-highlighting.markdown

@@ -1,13 +1,25 @@
-# Semantic highlighting
+---
+layout: default
+title: Semantic Highlighting for Themes
+parent: Ruby LSP
+nav_order: 30
+---
 
-The Ruby LSP supports semantic highlighting. This feature informs editors about the right token types for each part of
-the code to allow for rich and accurate highlighting. The strategy taken by the Ruby LSP is to only return tokens for
-syntax that is ambiguous in Ruby (as opposed to all existing tokens) to optimize for performance.
+# Semantic Highlighting for Themes
+
+Ruby LSP supports semantic highlighting, which informs editors about the right token types for each part of the code to
+the code to allow for rich and accurate highlighting. If you're a theme developer or want to enhance the Ruby syntax
+highlighting in your editor, this guide provides a brief overview of the semantic tokens available and how to use them.
+
+The strategy taken by Ruby LSP is to only return tokens for syntax that is ambiguous in Ruby (as opposed to all existing
+tokens) to optimize for performance.
 
 An example of ambiguous syntax in Ruby are local variables and method calls. If you look at this line in isolation:
+
 ```ruby
 foo
 ```
+
 it is not possible to tell if `foo` is a local variable or a method call. It depends on whether `foo` was assigned to
 something before or not. This is one scenario where semantic highlighting removes the ambiguity for themes, returning
 the correct token type by statically analyzing the code.

TROUBLESHOOTING.md → jekyll/troubleshooting.markdown

@@ -1,3 +1,9 @@
+---
+layout: default
+title: Troubleshooting
+nav_order: 20
+---
+
 # Troubleshooting
 
 ## How the Ruby LSP activation works
@@ -28,9 +34,9 @@ project. That directory contains another `Gemfile`, that includes the `ruby-lsp`
 dependencies. This approach allows us to automatically detect which formatter your project uses and which gems we need
 to index for features such as go to definition.
 
-> [!NOTE]
-> We are working with the RubyGems/Bundler team to have this type of mechanism properly supported from within
-> Bundler itself, which is currently being experimented with in a plugin called `bundler-compose`. Once
+{: .note }
+We are working with the RubyGems/Bundler team to have this type of mechanism properly supported from within
+Bundler itself, which is currently being experimented with in a plugin called `bundler-compose`. Once
 > `bundler-compose`is production ready, the entire custom bundle created under the `.ruby-lsp` directory will go away
 > and we'll rely on Bundler to compose the LOAD_PATH including the `ruby-lsp` gem.
 
@@ -40,15 +46,15 @@ There are several main sources of issues users typically face during activation:
 
 ### Outdated Version
 
-> [!NOTE]
+{: .note }
 > If using VS Code, the version of the extension is distinct from that of the server (the `ruby-lsp` gem). You can check the server version in the [status center](https://github.com/Shopify/ruby-lsp/blob/main/vscode/extras/ruby_lsp_status_center.png).
 
 In most cases, the server gem will be automatically updated. You can also trigger a manual update with the "Update language server gem" command in VS Code.
 
 You can also attempt an update from the command line with `BUNDLE_GEMFILE=.ruby-lsp/Gemfile bundle update ruby-lsp`
 
-> [!NOTE]
-> If you're using any addon gem, such as `ruby-lsp-rspec`, then `ruby-lsp` will also be present in your `Gemfile.lock` and it's possible that an outdated addon could prevent `ruby-lsp` from updating.
+{: .note }
+If you're using any addon gem, such as `ruby-lsp-rspec`, then `ruby-lsp` will also be present in your `Gemfile.lock` and it's possible that an outdated addon could prevent `ruby-lsp` from updating.
 
 Another possible scenario where the `ruby-lsp` gem cannot be updated is when one of its runtime dependencies are
 constrained by another gem in the application. For example, Ruby LSP has a dependency on
@@ -147,9 +153,9 @@ gem: --install-dir /my/preferred/path/for/gem/install
 One scenario where this is useful is if the user doesn't have permissions for the default gem installation directory and
 `gem install` fails. For example, when using the system Ruby on certain Linux distributions.
 
-> [!NOTE]
-> Using non-default gem installation paths may lead to other integration issues with version managers. For example, for
-> Ruby 3.3.1 the default `GEM_HOME` is `~/.gem/ruby/3.3.0` (without the patch part of the version). However, `chruby`
+{: .note }
+Using non-default gem installation paths may lead to other integration issues with version managers. For example, for
+Ruby 3.3.1 the default `GEM_HOME` is `~/.gem/ruby/3.3.0` (without the patch part of the version). However, `chruby`
 > (and potentially other version managers) override `GEM_HOME` to include the version patch resulting in
 > `~/.gem/ruby/3.3.1`. When you install a gem using `gem install --user-install`, RubyGems ignores the `GEM_HOME`
 > override and installs the gem inside `~/.gem/ruby/3.3.0`. This results in executables not being found because `chruby`
@@ -164,7 +170,7 @@ One scenario where this is useful is if the user doesn't have permissions for th
 
 ### Developing on containers
 
-See the [documentation](vscode/README.md#developing-on-containers).
+See the [documentation](https://github.com/Shopify/ruby-lsp/tree/main/vscode#developing-on-containers).
 
 ## Diagnosing the problem
 
@@ -193,17 +199,17 @@ Did it select your preferred version manager? You can define which version manag
 ### Enable logging
 
 You can enable logging to the VS Code output tab,
-[as described in the CONTRIBUTING](CONTRIBUTING.md#tracing-lsp-requests-and-responses) docs.
+[as described in the CONTRIBUTING](https://github.com/Shopify/ruby-lsp/blob/main/CONTRIBUTING.md#tracing-lsp-requests-and-responses) docs.
 
 ### Environment activation failed
 
-We listed version manager related information and tips in this [documentation](VERSION_MANAGERS.md).
+We listed version manager related information and tips in this [documentation](version-managers).
 
 ### My preferred version manager is not supported
 
 We default to supporting the most common version managers, but that may not cover every single tool available. For these
 cases, we offer custom activation support. More context in the version manager
-[documentation](VERSION_MANAGERS.md#custom-activation).
+[documentation](version-managers#custom-activation).
 
 ### Try to run the Ruby activation manually
 

VERSION_MANAGERS.md → jekyll/version-managers.markdown

@@ -1,3 +1,9 @@
+---
+layout: default
+title: Version Managers
+parent: Troubleshooting
+---
+
 # Version Managers
 
 This document contains information and tips to help Ruby LSP's VS Code extension work with your Ruby version manager.

lib/ruby_lsp/utils.rb

@@ -25,7 +25,7 @@ module RubyLsp
     end,
     String,
   )
-  GUESSED_TYPES_URL = "https://github.com/Shopify/ruby-lsp/blob/main/DESIGN_AND_ROADMAP.md#guessed-types"
+  GUESSED_TYPES_URL = "https://shopify.github.io/ruby-lsp/design-and-roadmap.html#guessed-types"
 
   # Request delegation for embedded languages is not yet standardized into the language server specification. Here we
   # use this custom error class as a way to return a signal to the client that the request should be delegated to the

vscode/README.md

@@ -27,7 +27,7 @@ Adding method support for definition, completion, hover and workspace symbol is
 See complete information about features [here](https://shopify.github.io/ruby-lsp/RubyLsp/Requests.html).
 
 If you experience issues, please see the [troubleshooting
-guide](https://github.com/Shopify/ruby-lsp/blob/main/TROUBLESHOOTING.md).
+guide](https://shopify.github.io/ruby-lsp/troubleshooting.html).
 
 ### [Experimental] GitHub Copilot chat agent
 
@@ -126,7 +126,7 @@ default shell.
 > [!NOTE]
 >
 > For manager-specific notes, setting up custom activation for managers not listed above and community-contributed
-> examples, please see [version managers](https://github.com/Shopify/ruby-lsp/blob/main/VERSION_MANAGERS.md).
+> examples, please see [version managers](https://shopify.github.io/ruby-lsp/version-managers.html).
 
 #### Configuring a formatter
 

vscode/src/client.ts

@@ -215,7 +215,7 @@ class ClientErrorHandler implements ErrorHandler {
       integration or Bundler issues.
 
       [Logs](command:workbench.action.output.toggleOutput) |
-      [Troubleshooting](https://github.com/Shopify/ruby-lsp/blob/main/TROUBLESHOOTING.md) |
+      [Troubleshooting](https://shopify.github.io/ruby-lsp/troubleshooting.html) |
       [Run bundle install](command:rubyLsp.bundleInstall?"${this.workspaceFolder.uri.toString()}")`,
       "Retry",
       "Shutdown",

vscode/src/ruby/custom.ts

@@ -33,7 +33,7 @@ export class Custom extends VersionManager {
     if (customCommand === undefined) {
       throw new Error(
         "The customRubyCommand configuration must be set when 'custom' is selected as the version manager. \
-        See the [README](https://github.com/Shopify/ruby-lsp/blob/main/VERSION_MANAGERS.md) for instructions.",
+        See the [README](https://shopify.github.io/ruby-lsp/version-managers.html) for instructions.",
       );
     }
 

vscode/src/workspace.ts

@@ -92,7 +92,7 @@ export class Workspace implements WorkspaceInterface {
       this.error = true;
       await vscode.window.showErrorMessage(
         `Failed to setup the bundle: ${error.message}. \
-        See [Troubleshooting](https://github.com/Shopify/ruby-lsp/blob/main/TROUBLESHOOTING.md) for help`,
+        See [Troubleshooting](https://shopify.github.io/ruby-lsp/troubleshooting.html) for help`,
       );
 
       return;