Add optional Modrinth projects support (? suffix) documentation

[Vianpyro]

Closes #3997

Summary

@Vianpyro will still need the documentation part of https://github.com/itzg/docker-minecraft-server/pull/3998/changes#diff-25b277033deeeef5aa02116dbc7e3cc7aea7a77c88ce9c83b3791a357b835e21

I'll cut a release to include this PR change though and get that included in the itzg/minecraft-server image.

Originally posted by @itzg in itzg/mc-image-helper#742 (comment)

Adds documentation for the optional Modrinth projects feature (? suffix), whose implementation lives in itzg/mc-image-helper#742.

Usage

MODRINTH_PROJECTS: |
  fabric-api
  lithium
  pl3xmap?
  bluemap?:beta

The ? works with all existing format variations: slug?, prefix:slug?, slug?:version, etc.

Combined with VERSION_FROM_MODRINTH_PROJECTS

Optional projects are excluded from version resolution, so they never block a Minecraft upgrade:

VERSION_FROM_MODRINTH_PROJECTS: true
MODRINTH_PROJECTS: |
  fabric-api
  lithium
  pl3xmap?

Changes

File	What changed
docs/mods-and-plugins/modrinth.md	New "Optional projects" section with syntax table and usage examples

Behavior

1. All mods available -> everything installs normally (no change in behavior)
2. Optional mod unavailable -> warning logged, startup continues without it
3. Required mod unavailable -> startup fails as before
4. Version resolution -> only required (non-?) projects determine the Minecraft version

[itzg]

To get the changes all together, go ahead and bump this to 1.56.0

docker-minecraft-server/Dockerfile

Line 58 in 2320547

ARG MC_HELPER_VERSION=1.55.4

[Vianpyro]

Done! Thank you very much for your help 😁

[itzg]

Thanks. Have you built an image locally and confirmed it all works as you're expecting?

https://docker-minecraft-server.readthedocs.io/en/latest/misc/building/

[Vianpyro]

Yes! Here are the Dockerfile and compose file I used:

docker compose up --build

FROM itzg/minecraft-server:java25

ARG MC_HELPER_VERSION=1.56.0

RUN set -eux; \
  curl -fsSL https://github.com/itzg/mc-image-helper/releases/download/${MC_HELPER_VERSION}/mc-image-helper-${MC_HELPER_VERSION}.tgz \
  | tar -C /usr/share -zxf -; \
  rm -f /usr/share/mc-image-helper; \
  ln -s /usr/share/mc-image-helper-${MC_HELPER_VERSION} /usr/share/mc-image-helper; \
  ln -sf /usr/share/mc-image-helper/bin/mc-image-helper /usr/bin/mc-image-helper

services:
  mc:
    build: .
    pull_policy: build
    restart: unless-stopped
    environment:
      EULA: true
      TYPE: "FABRIC"
      MODRINTH_PROJECTS: |
        fabric-api
        pl3xmap?:beta
    ports:
      - "25565:25565/tcp"
    volumes:
      - ./data:/data

And the logs I got:

[mc-image-helper] 14:46:31.709 INFO : Fabric launcher for minecraft 26.1.2 loader 0.18.6 is already available
[mc-image-helper] 14:46:33.750 WARN : Optional project 'Pl3xMap' has no compatible version for 26.1.2/fabric — skipping

[itzg]

Testing sounds perfect. Your approach helped me realize a manual build-test could be done against the repo itself with:

services:
  mc:
    build:
      # ...or wherever you cloned the docker-minecraft-server repo
      context: ../../..
      args:
        MC_HELPER_VERSION: 1.56.0
    environment:
      EULA: true
      TYPE: "FABRIC"
      MODRINTH_PROJECTS: |
        fabric-api
        pl3xmap?:beta
    ports:
      - "25565:25565/tcp"
    volumes:
      - ./data:/data

[Vianpyro]

That makes sense, thanks for the clarification!

I wasn’t aware the repo could be built directly like that with build args, that’s good to know. My initial approach was just to validate the fix in isolation by extending the base image.

Thank you very much for the quick reviews and merge!