jekpandocker

Dockerfile to generate a Docker image for helping in single source publishing, with all sources of documentation written in pandoc markdown and a publication workflow based on Jekyll, with pandoc as the Markdown rendering engine and theme based on Tufte. Output expected in HTML (Jekyll) and PDF.

Usage

How to run your Jekyll site in the container provided by fbab/jekpandocker ?

3 alternative usages described below:

• 1. Use on desktop the remote predefined image
• 2. Load in CI/CD the remote predefined image
• 3. Build on your own

Choose the one that fits your needs !

0. Prerequisites

• Suppose your desktop is Windows 10 (Powershell), Git installed, Docker installed and running (as administrator).
• Have a Jekyll site in C:\tmp\minimal

1. Use on desktop the remote predefined image

You can visit the image page on DockerHub.

docker pull fbab/jekpandocker

docker run --rm --name jekpandocker-container -v "C:\tmp\minimal:/srv/jekyll/" fbab/jekpandocker jekyll serve

You can then browse your Jekyll site on port 4000

browser> http://localhost:4000

2. Load in CI/CD the remote predefined image

The same image can be reffered in CI/CD scripts. Visit your Jekyll website at the address delivered by your CI/CD (Github Pages, Gitlab Pages, ...).

Github Actions

cf https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action

Gitlab

Example of .gitlab-ci.yml

image: fbab/jekpandocker
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public --trace --config _config.yml,_config_gitlab.yml
    - pwd
    - find . -name "*"
  artifacts:
    paths:
      # The folder that contains the files to be exposed at the Page URL ...
      - public
  rules:
    # This ensures that only pushes to the default branch will trigger
    # a pages deploy // $CI_COMMIT_REF_NAME
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

3. Build on your own

0A> open a Windows Powershell command (as administrator)

0B> cd /tmp

1A> git clone https://github.com/prodageo/jekpandocker

2A> (Get-Content 'copy/all/usr/jekyll/bin/bundle' -Raw) -match "\n$"

3A> cd /tmp/jekpandocker

4A> docker build -t jekpandocker-image .

5A> docker run --rm --name jekpandocker-container -v "C:\tmp\minimal:/srv/jekyll/" jekpandocker-image

Notes about some commands

2A

This command checks the line endings of files that will be read in the container. If returns false, probably the line endings of files have been set to crlf (\r\n) by git clone, check the git attribute value of core.autocrlf. Credits from Stackoverflow pseudo: Charles Ross, Antony Hatchkins

Credits

All this stuff would not have been possible without great work done in:

• https://github.com/envygeeks/jekyll-docker/blob/master/opts.yml
• https://github.com/p3palazzo/jekyll-pandoc-docker