Use a project.json file

A standalone project file can be used outside MakeMaker, or inside it when you want publication settings to change without regenerating the Makefile. The conventional filename is doc/project.json. The file may contain the publisher settings directly, beneath publish, or in the complete x_documentation.publish shape used by MakeMaker.

{
  "x_documentation": {
    "publish": {
      "module": "starlight",
      "name": "Example::Client",
      "sources": ["doc"],
      "output": "site",
      "branch": "gh-pages",
      "config_extend": "doc/starlight.extend.mjs"
    }
  }
}

Run the utility from the project root. It automatically reads doc/project.json when present, or accepts another path with --config.

markdown-publish build
markdown-publish serve
markdown-publish gh
markdown-publish gh-push

markdown-publish serve --config config/documentation.json

To make the MakeMaker targets read the same external file, set only config_file in the metadata. Do not combine it with inline publisher options.

x_documentation => {
    publish => {
        config_file => 'doc/project.json',
    },
},

The file is read when a target runs, so editing it does not require perl Makefile.PL. This is often the nicest arrangement for a project that changes themes and publishing details more often than its build metadata.