jekyll2cms converts markdown files into xml in order to export Jekyll blogs to content management systems. It is delivered as a docker image, which you can easily use in your blog.
jekyll2cms requires a Jekyll repository on GitHub. This repository will be used to convert its markdown files into xml files using the xml-template files in this repository. Repositories must adhere to structural requirements. Make sure to check out the adesso SE devblog as an example.
- The markdown files to be converted must be in the
_postsfolder. - The generated xml files will be located in
assets/first-spirit-xml. - The format of the generated xml files will be determined by
_layouts/post-xml.xml.
Running jekyll2cms requires some environment variables that must be passed to the docker run command or be defined as GitHub Secrets:
| Name | Description |
|---|---|
| REPOSITORY_LOCAL_USER_NAME | The GitHub username of the user who will commit the generated xml files to the repository. This user needs to have at least write access to the repository. If the branches are protected, this user needs admin access. |
| REPOSITORY_LOCAL_USER_PASSWORD | The password of this user. It is needed to provide the credentials to allow the commit. |
| REPOSITORY_LOCAL_USER_MAIL | The email of this user. This is needed to provide further commit information. |
| REPOSITORY_REMOTE_URL | The URL of the repository which contains the markdown files. This is also the location where the generated xml files are pushed to. |
Run jekyll2cms on your machine using the following command:
docker run -e REPOSITORY_REMOTE_URL=<repository_url> -e REPOSITORY_LOCAL_USER_NAME=<github_username> -e REPOSITORY_LOCAL_USER_MAIL=<github_email> -e REPOSITORY_LOCAL_USER_PASSWORD=<github_password> jekyll2cms/jekyll2cms:<tag>
It is also possible to use jekyll2cms as a GitHub Action - Create a workflow and copy the following steps. We recommend using GitHub Secrets to provide the configuration.
- name: Pull Docker image
run: docker pull <your_docker_hub_user>/<your_docker_hub_image>:<tag>
- name: Run Docker image
run: docker run -e REPOSITORY_REMOTE_URL='${{ secrets.REPOSITORY_REMOTE_URL }}' -e REPOSITORY_LOCAL_USER_NAME='${{ secrets.REPOSITORY_LOCAL_USER_NAME }}' -e REPOSITORY_LOCAL_USER_MAIL='${{ secrets.REPOSITORY_LOCAL_USER_MAIL }}' -e REPOSITORY_LOCAL_USER_PASSWORD='${{ secrets.REPOSITORY_LOCAL_USER_PASSWORD }}' <your_docker_hub_user>/<your_docker_hub_image>:<tag>
jekyll2cms is a Java Spring Boot application. The execution is separated into four steps.
- Check configuration
- Clone repository
- Execute
jekyll buildand copy generated xml files to specified folder - Commit and push generated files to remote repository
jekyll2cms will first check if the configuration and the associated environment variables are passed correctly.
The target repository will then be cloned.
jekyll build is executed and generates the xml files in the _site directory.
The generated xml files are moved from _site to assets/first-spirit-xml.
Images used in the markdown files are copied to assets/images.
jekyll2cms then checks if any files have changed.
This is done using git status in JGit.
Any changes are committed and pushed to the remote repository using a commit message that specifies the changes.
The process is finished without commits if no changes were detected.
jekyll2cms then exits.
jekyll2cms will exit successfuly if
- the generated xml files were pushed successfuly
- or if a commit doesn't containt new changes.
jekyll2cms will exit with code 0 in both cases.
jekyll2cms can fail during execution. Reasons might include misconfiguration or errors in Jekyll. We have defined error codes to make debugging easier.
| Exit code | Description |
|---|---|
| 01 | An error ocurred that is not handled by jekyll2cms. |
| 10 | Environment variable REPOSITORY_REMOTE_URL not found. |
| 11 | Environment variable REPOSITORY_LOCAL_USER_NAME not found. |
| 12 | Environment variable REPOSITORY_LOCAL_USER_MAIL not found. |
| 13 | Environment variable REPOSITORY_LOCAL_USER_PASSWORD not found. |
| 20 | Error while cloning remote repository. |
| 30 | Execution of jekyll build returned a non zero exit code. |
| 31 | Couldn't generate jekyll build. Execution directory not found. |
| 32 | Error calling generated jekyll build command. This is not an error with jekyll. |
| 33 | Error assembling files to copy. |
| 34 | Error copying genereated files. |
| 35 | Error copying images. |
| 40 | Error pushing files to remote repository. |
Feel free to fork and adapt jekyll2cms to your needs. We've prepared a short guide to help you get started.
Make sure that the following components are installed correctly on your system:
We highly recommend to always execute jekyll2cms using docker. This prevents errors due to missing environment variables or different path separators. However you can also use the jar to execute it.
To run your local changes using docker follow these steps:
- Rebuild your app with
gradlew build - Run
docker build -t jekyll2cmsto build a new image - Use the
docker runcommand as specified in Executing localy
On every commit on the master branch a new release for jekyll2cms is built using GitHub actions. The version number is defined in the docker-build-and-push.yml workflow file. If it is not changed the current image on docker hub is overwritten.
We do not provide any official support for this software. You can however create an issue in this repository if you have any questions, feedback or technical difficulties. You can also reach us at devblog[replace with the at-sign]adesso.de.