javalin / javalin/website

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

Open
#197 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
39
Forks
98
PR merge metrics
No merged PRs in 30d

Description

### 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](https://github.com/javalin/javalin.github.io#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](https://github.com/peteretelej/jekyll-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](https://github.com/javalin/javalin.github.io#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"]
```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.