Improving JSON schema support

[ssbarnea]

I opened this discussion to keep track of current problems identified with current version of the schema:

Bugs

• plugins > autorefs not recognized
• markdown_extensions > pymdownx.magiclink > repo_url_shortener, social_url_shorthand, social_url_shortener, normalize_issue_symbols not recognized
• markdown_extensions > markdown_include.include missing
• compile schema into single JSON file (no external references) as some loaders would have problems with multiple files, also this affects performance
• Sort the JSON schema file (prettier can do it) as editing it is a PITA when properties are not sorted.

Improvements

• adding schema to official schemastore. @ssbarnea Add mkdocs configuration file schema to the catalog SchemaStore/schemastore#2748)
• adding support to YAML vscode extension to load customTags from within the schema, so user would not need to edit configuration, @ssbarnea

[squidfunk]

Thanks for reporting. The schema is located in our docs folder – contributions are welcome via PRs. It is by no means complete, never will be due to the many external plugins and extensions there are. Thus, we need to rely on external contributors to gradually improve and complete it.

Compiling into a single file is likely not going to happen, since we have external schemas which we will lose track off when our docs don't change, i.e. we would need a docs rebuild each time an external schema changes. That's impractical.

[ssbarnea]

WIP to address these at #4905 still needs your blessing to run the CI.

[ssbarnea]

I started incorporating the missing bits that I spotted, so I can retire my own schema and rely on this one. Still, I due to the current setup I struggle to test my changes in vscode because even reloading the entire vscode does not reload the indirect files.

When I mentioned compiled, I meant the internal relative references, not external ones, like "$ref": "extensions/pymdownx.json" -- these are the issue.

For example, YAML extension is able to watch a schema file and reload it automatically from disk, allowing to see the effects of your schema modifications in real time. When using relative references this no longer works and for some reason it even fails with "Reload Window", which effectively restarts the language servers.

Clearly editing standalone files is easier than a big mega-json file, but that does not help testing the change.

[squidfunk]

I'm not having any problems when updating internally referred nested schemas in VS Code – the files and schema are always up to date. I'm using the YAML extension by Red Hat. This might be related to the file being local and contained within the repository:

mkdocs-material/.vscode/settings.json

Lines 11 to 13 in fab1f02

	"yaml.schemas": {
	"docs/schema.json": "mkdocs.yml"
	},

Thus, I'm not considering including a build step for the reasons stated.