Uses Jekyll to generate the documentation.

- Uses Jekyll to generate the documentation, which's source and configs
  live in the `/jekyll` folder.
- The documentation will still be built to the `/docs` folder and be
  ignored by git.
- Currently, the documentation is one big page (similar to rust-analyzer's).
- All the current feature demos and introduction are copied from the
  Code Navigation post on the Rails At Scale blog. We will gradually
  fill in the rest of the documentation.
- To avoid duplication, most of README's content has been moved to the
  documentation too.
- Because Jekyll server isn't able to link to assets outside of the source
  directory, we need to copy the Ruby LSP icon to `/jekyll` folder.

.github/workflows/publish_docs.yml

@@ -23,13 +23,10 @@ jobs:
           git config user.email [email protected]
 
       - name: Generate documentation
-        run: bundle exec rake rdoc
-
-      - name: Copy README images to the docs folder
+        working-directory: ./jekyll
         run: |
-          mkdir docs/vscode
-          cp vscode/icon.png docs/vscode/icon.png
-          cp -R vscode/extras docs/vscode/
+          bundle install
+          bundle exec jekyll build
 
       - name: Commit to gh-pages
         run: |

.rubocop.yml

@@ -20,6 +20,7 @@ AllCops:
     - "features/**/*"
     - "test/fixtures/**/*"
     - "test/expectations/**/*"
+    - "jekyll/**/*"
 
 Minitest/AssertPredicate:
   Enabled: true

CONTRIBUTING.md

@@ -1,5 +1,15 @@
 # CONTRIBUTING
 
+## Contributing to documentation
+
+Ruby LSP uses [Jekyll](https://jekyllrb.com/) to generate the documentation, which's source lives under the `/jekyll` folder.
+
+```shell
+cd jekyll
+bundle install
+bundle exec jekyll serve # Builds the site and serves it at http://localhost:4000/ruby-lsp
+```
+
 ## Testing changes
 
 ### Tracing LSP requests and responses

README.md

@@ -15,119 +15,9 @@ experience to Ruby developers using modern standards for cross-editor features,
 Want to discuss Ruby developer experience? Consider joining the public
 [Ruby DX Slack workspace](https://join.slack.com/t/ruby-dx/shared_invite/zt-2c8zjlir6-uUDJl8oIwcen_FS_aA~b6Q).
 
-## Features
+## Getting Started
 
-![Ruby LSP demo](vscode/extras/ruby_lsp_demo.gif)
-
-The Ruby LSP features include
-
-- Semantic highlighting
-- Symbol search and code outline
-- RuboCop errors and warnings (diagnostics)
-- Format on save (with RuboCop or Syntax Tree)
-- Format on type
-- Debugging support
-- Running and debugging tests through VS Code's UI
-- Go to definition for classes, modules, constants and required files
-- Showing documentation on hover for classes, modules and constants
-- Completion for classes, modules, constants and require paths
-- Fuzzy search classes, modules and constants anywhere in the project and its dependencies (workspace symbol)
-
-As of July 2024, Ruby LSP has received significant enhancements to its code navigation features. For an in-depth look at these improvements, including video demonstrations, check out this [article](https://railsatscale.com/2024-07-18-mastering-ruby-code-navigation-major-enhancements-in-ruby-lsp-2024/). Despite these advancements, we plan to continue enhancing its code navigation support even further. You can follow our progress on this [GitHub issue](https://github.com/Shopify/ruby-lsp/issues/899).
-
-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).
-
-## Usage
-
-### With VS Code
-
-If using VS Code, all you have to do is install the [Ruby LSP
-extension](https://marketplace.visualstudio.com/items?itemName=Shopify.ruby-lsp) to get the extra features in the
-editor. Do not install the `ruby-lsp` gem manually.
-
-For more information on using and configuring the extension, see [vscode/README.md](vscode/README.md).
-
-### With other editors
-
-See [editors](EDITORS.md) 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
-```shell
-gem install ruby-lsp
-```
-
-and the language server can be launched running `ruby-lsp` (without bundle exec in order to properly hook into your
-project's dependencies).
-
-### Documentation
-
-See the [documentation](https://shopify.github.io/ruby-lsp) for more in-depth details about the
-[supported features](https://shopify.github.io/ruby-lsp/RubyLsp/Requests.html).
-
-For creating rich themes for Ruby using the semantic highlighting information, see the [semantic highlighting
-documentation](SEMANTIC_HIGHLIGHTING.md).
-
-### Configuring code indexing
-
-By default, the Ruby LSP indexes all Ruby files defined in the current project and all of its dependencies, including
-default gems, except for
-
-- Gems that only appear under the `:development` group
-- All Ruby files under `test/**/*.rb`
-
-This behaviour can be overridden and tuned. Learn how to configure it [for VS Code](vscode/README.md#Indexing-Configuration) or [for other editors](EDITORS.md#Indexing-Configuration).
-
-Note that indexing-dependent behavior, such as definition, hover, completion or workspace symbol will be impacted by
-the configuration changes.
-
-The older approach of using a `.index.yml` file has been deprecated and will be removed in a future release.
-
-```yaml
-# Exclude files based on a given pattern. Often used to exclude test files or fixtures
-excluded_patterns:
-  - "**/spec/**/*.rb"
-
-# Include files based on a given pattern. Can be used to index Ruby files that use different extensions
-included_patterns:
-  - "**/bin/*"
-
-# Exclude gems by name. If a gem is never referenced in the project's code and is only used as a tool, excluding it will
-# speed up indexing and reduce the amount of results in features like definition or completion
-excluded_gems:
-  - rubocop
-  - pathname
-
-# Include gems by name. Normally used to include development gems that are excluded by default
-included_gems:
-  - prism
-```
-
-### Addons
-
-The Ruby LSP provides an addon system that allows other gems to enhance the base functionality with more editor
-features. This is the mechanism that powers addons like
-
-- [Ruby LSP Rails](https://github.com/Shopify/ruby-lsp-rails)
-- [Ruby LSP RSpec](https://github.com/st0012/ruby-lsp-rspec)
-- [Ruby LSP rubyfmt](https://github.com/jscharf/ruby-lsp-rubyfmt)
-
-Additionally, some tools may include a Ruby LSP addon directly, like
-
-- [Standard Ruby (from v1.39.1)](https://github.com/standardrb/standard/wiki/IDE:-vscode#using-ruby-lsp)
-
-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](ADDONS.md).
-
-## Learn More
-
-* [RubyConf 2022: Improving the development experience with language servers](https://www.youtube.com/watch?v=kEfXPTm1aCI) ([Vinicius Stock](https://github.com/vinistock))
-* [Remote Ruby: Ruby Language Server with Vinicius Stock](https://remoteruby.com/221)
-* [RubyKaigi 2023: Code indexing - How language servers understand our code](https://www.youtube.com/watch?v=ks3tQojSJLU) ([Vinicius Stock](https://github.com/vinistock))
+Please refer to the official [documentation](https://shopify.github.io/ruby-lsp) for more information about [installation and usage](https://shopify.github.io/ruby-lsp#usage) and [supported features](https://shopify.github.io/ruby-lsp#features).
 
 ## Contributing
 

jekyll/.gitignore

@@ -0,0 +1,5 @@
+_site
+.sass-cache
+.jekyll-cache
+.jekyll-metadata
+vendor

jekyll/404.html

@@ -0,0 +1,25 @@
+---
+permalink: /404.html
+layout: default
+---
+
+<style type="text/css" media="screen">
+  .container {
+    margin: 10px auto;
+    max-width: 600px;
+    text-align: center;
+  }
+  h1 {
+    margin: 30px 0;
+    font-size: 4em;
+    line-height: 1;
+    letter-spacing: -1px;
+  }
+</style>
+
+<div class="container">
+  <h1>404</h1>
+
+  <p><strong>Page not found :(</strong></p>
+  <p>The requested page could not be found.</p>
+</div>

jekyll/Gemfile

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+# Hello! This is where you manage which Jekyll version is used to run.
+# When you want to use a different version, change it below, save the
+# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
+#
+#     bundle exec jekyll serve
+#
+# This will help ensure the proper Jekyll version is running.
+# Happy Jekylling!
+gem "jekyll", "~> 4.3.3"
+
+# Theme
+gem "just-the-docs", "~> 0.10.0"
+
+# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
+# uncomment the line below. To upgrade, run `bundle update github-pages`.
+# gem "github-pages", group: :jekyll_plugins
+# If you have any plugins, put them here!
+group :jekyll_plugins do
+  gem "jekyll-feed", "~> 0.12"
+end
+
+# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
+# and associated library.
+platforms :mingw, :x64_mingw, :mswin, :jruby do
+  gem "tzinfo", ">= 1", "< 3"
+  gem "tzinfo-data"
+end
+
+# Performance-booster for watching directories on Windows
+gem "wdm", "~> 0.1.1", platforms: [:mingw, :x64_mingw, :mswin]
+
+# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem
+# do not have a Java counterpart.
+gem "http_parser.rb", "~> 0.6.0", platforms: [:jruby]