More detailed guidance on how to build the Javalin documentation web site
- 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
Assessment
This issue has not been assessed yet.