More detailed guidance on how to build the Javalin documentation web site

[northcoder-repo]

Objective

Make it easier for users (like me) to contribute documentation updates for the Javalin web site.

REQUEST: Can the community provide a better Docker-based (or even non-Docker-based) approach for Windows users? See my attempt below.

Updates could be added to the readme page.

My Problem

When I recently submitted my first ever document change, I spent most of my time trying to set up a compatible Ruby/Jekyll environment with the correct set of gems, at the required versions to build the javalin.io site. This was definitely my problem, not related to the Javalin web site.

My main PC is Windows - which seems to have been at the root of my problems. See "alternatives" below for details.

Ideal Solution

I ended up using an updated dockerfile based on an older Jekyll Docker Container I found. I had to make some changes to that file. I have shared my end result below. But even with my modified dockerfile, the web site did not seem to build 100% correctly, locally - for example, the Java code on the home page does not have syntax highlighting (whereas the Kotlin code does - and Java code elsewhere seems OK).

So, I am not convinced that my Docker image is entirely correct - but it is good enough to be usable.

Perhaps the community can provide a better Docker-based (or even non-Docker-based) approach for Windows users? Clearly there are plenty of users who have been able to contribute to the Javalin documentation - probably without the struggle I had.

Maybe the end result could be added to the readme page. I would be happy to make that pull request myself, based on any feedback provided here.

Alternatives

Before I used my Docker approach, I tried:

• Chocolatey on Windows to install Ruby, Bundler and Jekyll. That led to many missing components.
• Ruby installer with devkit on Windows. That led to similar issues - especially with trying to compile native gems.
• A Linux-based approach (Amazon AMI2). That led to a failed Nokogiri build.

Even with the Docker approach, I had to experiment a bit with different Ruby versions. I failed to build the Javalin site using Ruby 3.1.3 - and ended up using Ruby 2.7.7.

My Dockerfile

This uses the Gemfile from copied from this GitHub project.

#
# An updated version of https://github.com/peteretelej/jekyll-container
#
FROM ruby:2.7.7-bullseye

RUN mkdir -p /etc/jekyll

COPY Gemfile /etc/jekyll

RUN apt-get -qq update && \
  apt-get -qq install nodejs -y && \
  gem install -q bundler -v 1.12.3 && \
  bundle install --gemfile /etc/jekyll/Gemfile && \
  apt-get clean && \
  rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

ENV BUNDLE_GEMFILE /etc/jekyll/Gemfile

EXPOSE 4000

ENTRYPOINT ["bundle", "exec"]

CMD ["jekyll", "serve", "--host=0.0.0.0", "--future", "--incremental"]

[tipsy]

Thanks for reporting this @northcoder-repo. This has been a recurring problem over many years, I struggle with the same on both Windows and MacOS. I am scared to touch my current setup, because it took a long time to get it right. I'm also scared to upgrade to 3x, for the same reason.

It seems a lot of people have tried to solve this using Docker, but with mixed results. As a short term solution, I'm happy to include your dockerfile in the repo itself.

As for a long term solution... It's hard to believe that it's still this difficult to setup Ruby and Jekyll 2023, and it doesn't seem to be getting any easier. Maybe it's time to look for alternatives. I know that Hugo used to have an "import from Jekyll" feature. Maybe it's something we should look into.

[zugazagoitia]

Clearly there are plenty of users who have been able to contribute to the Javalin documentation - probably without the struggle I had.

I really wish that was true.

The fact that the preview CI workflow works it's something that I still don't understand (I did it myself 😐).

I've attempted to use docker locally and got it working with some tweaks.
I.e. I had to delete the .lock file locally to successfully build due to some quirky gems. I'm supposedly using the same ruby version as @tipsy and still run into issues.

I think the way to go for now would be to update the gems/ruby to a more current (and frankly accesible since I had to dig a lot to download the current one) version and lock it. I could try and make a custom javalin docker container for development that works but I'm afraid of what's waiting for me that way 😳.