Jekyll PlantUML

This is the repositry for the swedbankpay/jekyll-plantuml Docker image. The purpose of the image is to have a shared Docker image to run Jekyll sites with PlantUML support (via the kramdown-plantuml Ruby Gem).

Usage

Commands

The Docker image is outfitted with an entrypoint that allows you to run a few commands inside the container. these commands are described below.

Serve

To have Jekyll serve content from the current working directory, simply execute the following:

docker run --tty --volume $(pwd):/srv/jekyll swedbankpay/jekyll-plantuml:latest serve

Build

To build the content in the current working directory and have the results spit out to a _site sub-directory, execute the following:

docker run --tty --volume $(pwd):/srv/jekyll swedbankpay/jekyll-plantuml:latest build

The build command also takes an argument:

--verify

Verifies that the built HTML is valid using HTMLProofer.

Deploy

There is also a special deploy command which will execute Git Directory Deploy in order to perform a jekyll build and then deploy the resulting HTML to the gh-pages branch (by default):

docker run --tty \
    --volume $(pwd):/srv/jekyll \
    --env GIT_DEPLOY_REPO="${GIT_DEPLOY_REPO}" \
    --env GIT_DEPLOY_BRANCH="${GIT_DEPLOY_BRANCH}" \
    swedbankpay/jekyll-plantuml:latest \
    deploy

The deploy command takes the following environment variables:

GIT_DEPLOY_REPO

Required. The URL of the repository to deploy (git push) to. Must include a Personal Access Token in the URL as such:

https://${{ secrets.GH_PAGES_TOKEN }}@github.com/${{ github.repository }}.git

GIT_DEPLOY_BRANCH

Optional. The branch to deploy to. Default gh-pages.

The deploy command also takes arguments:

--dry-run

Performs a full deployment, but doesn't push the results to the remote origin.

Volume

The Docker image exposes one volume: /srv/jekyll. Map this to the local directory you want Jekyll to use as its source content directory for jekyll build, jekyll serve, etc. Simply put, this is where your .md files are placed.

Configuration

While it is highly recommended to install Jekyll locally and initialize a Jekyll site with jekyll new <name>, this is not required to serve or convert .md files with jekyll-plantuml.

This is achieved by shipping a default Gemfile and default _config.default.yml with the Docker container that is used in the case that a Gemfile and/or _config.yml file can't be found locally.

If you want a full Jekyll site with local config, custom plugins, etc., you need to install Jekyll and initialize the folder you build or serve with it according to Jekyll's documentation.

Contributing

Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct and sign the contributor's license agreement.

License

The code within this repository is available as open source under the terms of the Apache 2.0 License and the contributor's license agreement.