`--extra-settings` argument escaping not documented for Windows shells

[multiplemonomials]

• [X] I have read the Filing Issues and subsequent “How to Get Help” sections of the documentation.
• [X] I can reproduce this problem with stock/default settings file, theme, and sample content (as described in above “How to Get Help” sections of the documentation).
• [X] I have searched the issues (including closed ones) and believe that this is not a duplicate.

• OS version and name: Windows 11
• Python version: 3.13.1
• Pelican version: 4.11
• Link to theme: N/A
• Links to plugins: N/A
• Link to your site: N/A
• Link to your source: N/A

Issue

Hi! I've gone through a bit of... fun... trying to use the --extra-settings option to Pelican to pass a string value on a Windows shell.

The Pelican CLI help simply says, for this option:

Values specified via -e / --extra-settings flags must be in JSON notation. Use -e KEY='"string"' to specify a string value.

However, doing this on Windows does not work:

> pelican -r -l -e SITEURL='"foo'"
Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "J:\Code-Delicious\venv\Scripts\pelican.exe\__main__.py", line 7, in <module>
    sys.exit(main())
<snip>

I did a little digging into the Pelican source code, and it looks like what it actually wants, at the Python level, is a string like SITEURL="foo". The single quotes in the CLI help are for Bash-style quoting. And indeed, that command does work if I run it in git bash!

In Command Prompt (cmd.exe), it seems like the right way to do this is to surround the parameter in double quotes, then use double double quotes inside the parameter:

> pelican -r -l -e "SITEURL=""foo"""
  --- AutoReload Mode: Monitoring `content`, `theme` and `settings` for changes. ---

This works, and correctly passes a single " around the value to the application.

In PowerShell (which is now the default on recent Windows versions), the situation gets even weirder. It seems like the easiest way is to make the argument a single quoted string, then escape each double quote with a backslash:

PS > pelican -r -l -e 'SITEURL=\"foo\"'    
  --- AutoReload Mode: Monitoring `content`, `theme` and `settings` for changes. ---

For my last trick, I would like to set this up as a VS Code task so that I can run it from the IDE. After some messing around, I landed on the following configuration:

{
	"version": "2.0.0",
	"tasks": [
        {
            "label": "Build, Watch, and Serve Site",
            "type": "process",
            "command": "${workspaceFolder}\\venv\\Scripts\\python.exe",
            "args": ["-m", "pelican", "-r", "-l", "-e", "SITEURL=\"http://127.0.0.1:8000\""],
            "isBackground": true,
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "presentation": {
                "reveal": "always",
                "panel": "shared",
                "showReuseMessage": false
            },
			"problemMatcher": [
				{
                    "source": "pelican",
                    "fileLocation": "absolute",
					"pattern": [
						{
                            "kind": "file",
							"regexp": "Skipping (.+): (.+)",
							"file": 1,
							"message": 2
						}
					],
					"background": {
						"activeOnStart": true,
						"beginsPattern": "re-generating...",
						"endsPattern": "Done: Processed [0-9]+ articles",
					}
				}
			],
        }
    ]
}

which seems to work. However, you have to be very careful to use "type": "process" and not "type": "shell", or you will run into the issues above with escaping with a vengeance!

Anyway, thank you for hearing me out on this! I think that it would be awesome if we could add more info to the docs on how to properly escape this argument. Even though the Windows escaping rules are objectively totally bonkers, they cause a lot of problems for people trying to use this feature of Pelican, so I think we should try and explain how to use them.