Uses Jekyll to generate the documentation

[st0012]

Motivation

Compared to RDoc, Jekyll is a much better platform for non-API-focused documentation. Some useful features for us are:

• Rich themes to choose from
• Easily-customizable templates
• Easy configuration with _config.yml
• Feature-rich markdown syntax support (e.g. supporting html tags too)

Implementation

• 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.

Demo

Screen.Recording.2024-09-10.at.21.44.44.mov

Automated Tests

Manual Tests

[andyw8]

Saw these mentioned yesterday, could be useful if we want to use Tailwind for styling.

https://github.com/skatkov/jekyll-tailwind-cli-template
https://github.com/crbelaus/jekyll-tailwind

[andyw8]

Is there somewhere else we could host the videos to avoid bloating the repo? They don't take up much space currently, but each time we update them the repo will grow.

[andyw8]

Once shipped, we should link to this from https://shopify.github.io/ to help with SEO.

It's already there.

[st0012]

Is there somewhere else we could host the videos to avoid bloating the repo? They don't take up much space currently, but each time we update them the repo will grow.

Vini and I talked about this before, specifically with Git LFS as the potential solution. But IMO we should focus on improving the content until RailsWorld and then worry about this later.

[vinistock]

Looks good to me. I left a couple of comments regarding the content, but I would rather have we move forward with the platform changes and then iterate on the content than holding this PR back

[st0012]

@vinistock because sass-embedded, a dependency of jekyll, fails to build with Ruby 3.1 and takes significantly longer to build with 3.2 (due to its build script relying on psych 5.1+, which only uses the version bundled with Ruby). Since Jekyll is only needed for documentation, I don't want to complicate the CI setup for it.
Given that ruby-lsp doesn't have dependabot working atm anyway (due to rbi requires Ruby 3.1 constantly failing it), can we maintain a separate Gemfile for Jekyll for now?

[vinistock]

@st0012 would this work?

• Put jekyll related gems in an optional Gemfile group, like group: :documentation
• Use The setup-ruby's action bundle config through environment variables to only include the group when generating the docs. It should just be a matter of using "BUNDLE_WITH": "documentation" in the config