Contributing to Jmix Guides

Thank you for your interest in contributing to the Jmix documentation! This guide will walk you through the process of creating and integrating a new example project for Jmix guides. We’ll use the jmix-petclinic repository as the base example to help you set up, adapt, and publish a new project within the Jmix framework.

Guide Contribution

To create a new Jmix guide, follow these steps:

How to Create an Example for a New Jmix Guide

In order to write a guide based on the Jmix petclinic the following steps should be taken:

Step 0: Setup a temporary environment variable

Set up an environment variable to define the core name of your guide. This will help keep naming consistent across commands:

export GUIDE_NAME=business-logic

Step 1: Clone the Base Repository

Clone the base jmix-petclinic repository to your local machine:

git clone git@github.com:jmix-framework/jmix-petclinic.git

This repository provides a template with existing configurations that simplify the setup for new examples.

Step 2: Set Up a New Repository for Your Guide

Make a copy of the cloned repository, renaming it according to the topic you’re covering:

cp -R jmix-petclinic jmix-$GUIDE_NAME-sample

Follow the jmix-topic-name-sample naming pattern to keep repository names consistent.

Then create a new repository in the Jmix GitHub organization:

gh repo create jmix-framework/jmix-$GUIDE_NAME-sample --public

Step 3: Configure Git Remotes

Point your local repository to the new GitHub repository:

git remote set-url origin git@github.com:jmix-framework/jmix-$GUIDE_NAME-sample.git

Then add the original jmix-petclinic repository as the upstream remote, so you can easily pull updates from it:

git remote add upstream git@github.com:jmix-framework/jmix-petclinic.git

You can confirm your remote configuration via:

git remote -v

Step 4: Adjust Project Settings

In settings.gradle, change the rootProject.name from jmix-petclinic to match your new project name:

echo "rootProject.name = 'jmix-$GUIDE_NAME-sample'" > settings.gradle

Step 5: Implement Your Example

Now you’re ready to develop your example! Add the custom business logic, configurations, or other adjustments specific to your guide’s topic.

Step 6: Keep Up with Upstream Changes

Occasionally, update your example with any new changes from the jmix-petclinic upstream repository to stay consistent with base improvements:

git fetch upstream
git checkout main
git merge upstream/main

Integrating Your Guide with the Jmix Docs

Once your example is ready, it’s time to integrate it with the main Jmix documentation repository.

Step 1: Rename the Docs Directory

Change the petclinic-guide directory to match the new guide name:

mv doc/modules/petclinic-guide doc/modules/$GUIDE_NAME-guide

Step 2: Integrate with the Main Docs Repository

In the main Jmix Docs repository, update the settings.gradle to clone your example locally. For example:

cloneOrPull('https://github.com/jmix-framework/jmix-$GUIDE_NAME-sample', 'external/jmix-$GUIDE_NAME-sample')
includeBuild 'external/jmix-$GUIDE_NAME-sample'

Additionally, you have to add the source root to the Antora playbook antora-playbook.yml:

content:
  sources: 
  - url: ./external/jmix-$GUIDE_NAME-sample
    branches: HEAD
    start_path: doc

On the antora-playbook.ci.yaml the definition also needs to be there, but is slightly different:

content:
  sources:
    - url: https://github.com/jmix-framework/jmix-$GUIDE_NAME-sample.git
      branches:
        - main
      start_path: doc

Finally, you have to add the guide to the main navigation Asciidoc file nav.adoc:

* xref:ROOT:guides.adoc[]
** xref:$GUIDE_NAME-guide:index.adoc[]

From now on you are able to write the docs directly in the jmix-docs IntelliJ IDEA project, which allows the Asciidoc plugin to recognise xref references correctly.

Once your Jmix guide is complete, open a Pull Request in the Jmix Docs repository. The Jmix team will review and collaborate with you on any necessary adjustments.

---

Image budget

To keep the repository small and clone times fast, image contributions are subject to size limits:

Type	Limit	Notes
PNG / WEBP	500 KB	Run pngquant --quality=65-85 --strip --force --ext .png file.png to optimize
JPG / JPEG	500 KB	Re-export at lower quality (75-85) or smaller dimensions
SVG	100 KB	If an SVG is large, it usually contains embedded base64 raster data — extract or re-export
GIF	not allowed	Host animated demos externally (YouTube, Vimeo, asciinema) and link from .adoc

The limits are enforced by a pre-commit hook and a CI check.

Enable the pre-commit hook (one-time, per clone)

git config core.hooksPath .githooks

The hook lives at .githooks/pre-commit. It scans staged image files and rejects commits that violate the rules. If you ever need to bypass it: git commit --no-verify.

Optimizing PNG screenshots

# Install pngquant once:
brew install pngquant      # macOS
sudo apt install pngquant  # Linux

# Then in the repo root:
pngquant --quality=65-85 --strip --force --ext .png path/to/screenshot.png

Typical reduction for UI screenshots: 70-80% size, no visible quality loss.

Repository history

This repository was created in May 2026 with a fresh history; previous history (including pre-cleanup image revisions) is preserved in the archived repo at [TBD: link to old repo]. Refer there for git blame and commit history older than the initial commit.