Refine guideline "Set up a local workspace" (#9355)

.github/workflows/deployment.yml

@@ -31,7 +31,6 @@ concurrency:
   group: ${{ github.ref }}
   cancel-in-progress: true
 
-
 jobs:
   build:
     strategy:

.github/workflows/pages.yml

@@ -1,6 +1,10 @@
 name: Deploy Jekyll site to Pages
 
 on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/pages.yml'
   push:
     paths:
       - 'docs/**'
@@ -27,19 +31,21 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.0' # Not needed with a .ruby-version file
+          ruby-version: '2.7' # Not needed with a .ruby-version file
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
-          cache-version: 0 # Increment this number if you need to re-download cached gems
+          cache-version: 1 # Increment this number if you need to re-download cached gems
+          working-directory: docs/
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v2
       - name: Build with Jekyll
-        uses: actions/jekyll-build-pages@v1
-        with:
-          source: docs/
-          destination: ./_site
+        run: |
+          cd docs
+          bundle exec jekyll build
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v1
+        with:
+          path: docs/_site/
 
   deploy:
     if: github.ref == 'refs/heads/main'

docs/.dockerignore

@@ -0,0 +1,3 @@
+.jekyll-cache
+.jekyll-metadata
+_site/

docs/.gitignore

@@ -1,2 +1,4 @@
+Gemfile.lock
 .jekyll-cache
+.jekyll-metadata
 _site/

docs/Dockerfile

@@ -0,0 +1,14 @@
+FROM ruby:2.7
+
+ENV LC_ALL C.UTF-8
+ENV LANG en_US.UTF-8
+ENV LANGUAGE en_US.UTF-8
+
+EXPOSE 4000
+
+WORKDIR /srv/jekyll
+COPY . /srv/jekyll
+
+RUN gem install bundler && bundle install
+
+CMD bundle exec jekyll serve -H 0.0.0.0 -t

docs/Gemfile

@@ -1,6 +1,19 @@
 source 'https://rubygems.org'
 
-gem "jekyll", "~> 4.2" # installed by `gem jekyll`
-gem "webrick"          # required when using Ruby >= 3
+gem "jekyll", "~> 4.3" # installed by `gem jekyll`
+
+# Homepage: https://github.com/paulrobertlloyd/jekyll-figure#jekyll-figure
+gem 'jekyll-figure'
 
 gem "just-the-docs", "0.4.0.rc3"
+
+gem "jekyll-remote-theme"
+
+# Added, because defualt layout with path "**/*.md" does not work at Jekyll
+#   Source: https://jekyllrb.com/docs/configuration/front-matter-defaults/#glob-patterns-in-front-matter-defaults
+# Homepage: https://github.com/benbalter/jekyll-default-layout#jekyll-default-layout
+gem 'jekyll-default-layout'
+
+# Somehow, "title" is set "magically" when on GitHub, but not when running locally
+# Homepage: https://github.com/benbalter/jekyll-titles-from-headings#jekyll-titles-from-headings
+gem 'jekyll-titles-from-headings'

docs/README.md

@@ -19,7 +19,11 @@ and go to <http://localhost:4000/> in your browser.
 On **Windows**, using a dockerized environment is recommended:
 
 ```terminal
-docker run -p 4000:4000 --rm --volume="C:\git-repositories\jabref\docs":/srv/jekyll jekyll/jekyll:4 jekyll serve
+docker build . -t jrjekyll
+docker run -p 4000:4000 -it --rm --volume="C:\git-repositories\jabref\docs":/srv/jekyll jrjekyll jekyll serve -H 0.0.0.0 -t
 ```
 
-In case you get errors regarding `Gemfile.lock`, just delete `Gemfile.lock` and rerun.
+* With <kbd>Ctrl</kbd>+<kbd>C</kbd> you can stop the server (this is enabled by the `-it` switch).
+* In case you get errors regarding `Gemfile.lock`, just delete `Gemfile.lock` and rerun.
+* The current `Dockerfile` is based on <https://github.com/just-the-docs/just-the-docs/blob/main/Dockerfile>.
+  The [Jekyll Docker image](https://github.com/envygeeks/jekyll-docker#jekyll-docker) did not work end of 20222 (because Ruby was too new).

docs/_config.yml

@@ -3,6 +3,8 @@ title: "Developer Documentation"
 remote_theme: just-the-docs/just-the-docs@v0.4.0.rc3
 color_scheme: light
 
+exclude: [CNAME, README.md, mkdocs-custom.css]
+
 # Hint by https://github.com/just-the-docs/just-the-docs/issues/374#issuecomment-680273258
 # Theme read from https://github.com/StylishThemes/Syntax-Themes/blob/master/pygments/css-github/
 # Browse alternative themes at https://stylishthemes.github.io/Syntax-Themes/pygments/
@@ -34,4 +36,28 @@ baseurl: ""
 url: ""
 
 plugins:
+  - jekyll-default-layout
+  - jekyll-figure
   - jekyll-remote-theme
+  - jekyll-titles-from-headings
+
+jekyll-figure:
+  paragraphs: false
+
+callouts_level: quiet # or loud
+callouts:
+  highlight:
+    title: Summary
+    color: blue
+  important:
+    title: Important
+    color: yellow
+  new:
+    title: New
+    color: green
+  note:
+    title: Note
+    color: purple
+  warning:
+    title: Warning
+    color: red

docs/_sass/custom/custom.scss

@@ -0,0 +1,8 @@
+figcaption {
+    font-size: .75em;
+    font-weight: 550;
+}
+
+figcaption:before {
+    content: "Figure: "
+}