diff --git a/src/api/json/catalog.json b/src/api/json/catalog.json index 13a1f5c3ca5..8e8fd9f5115 100644 --- a/src/api/json/catalog.json +++ b/src/api/json/catalog.json @@ -2198,6 +2198,12 @@ "fileMatch": ["**/assets/*/sounds.json"], "url": "https://raw.githubusercontent.com/AxoCode/json-schema/master/minecraft/sounds.json" }, + { + "name": "MkDocs Configuration 1.0", + "description": "JSON schema for MkDocs configuration file", + "fileMatch": ["mkdocs.yml"], + "url": "https://json.schemastore.org/mkdocs-1.0.json" + }, { "name": ".mocharc", "description": "JSON schema for MochaJS configuration files", diff --git a/src/schemas/json/mkdocs-1.0.json b/src/schemas/json/mkdocs-1.0.json new file mode 100644 index 00000000000..abd8242afff --- /dev/null +++ b/src/schemas/json/mkdocs-1.0.json @@ -0,0 +1,206 @@ +{ + "$schema": "http://json-schema.org/draft-04/schema#", + "allOf": [ + { + "$ref": "#/definitions/coreProperties" + }, + { + "required": ["site_name"] + } + ], + "definitions": { + "coreProperties": { + "type": "object", + "properties": { + "site_name": { + "description": "The main title for the project documentation.\nhttps://www.mkdocs.org/user-guide/configuration/#site_name", + "type": "string" + }, + "site_url": { + "description": "Set the canonical URL of the site. This will add a link tag with the canonical URL to the head section of each HTML page. If the 'root' of the MkDocs site will be within a subdirectory of a domain, be sure to include that subdirectory in the setting (https://example.com/foo/).\nhttps://www.mkdocs.org/user-guide/configuration/#site_url", + "type": "string" + }, + "repo_url": { + "description": "When set, provides a link to your repository (GitHub, Bitbucket, GitLab, ...) on each page.\nhttps://www.mkdocs.org/user-guide/configuration/#repo_url", + "type": "string" + }, + "repo_name": { + "description": "When set, provides the name for the link to your repository on each page.\nhttps://www.mkdocs.org/user-guide/configuration/#repo_name", + "type": "string" + }, + "edit_uri": { + "description": "The path from the base repo_url to the docs directory when directly viewing a page, accounting for specifics of the repository host (e.g. GitHub, Bitbucket, etc), the branch, and the docs directory itself.\nhttps://www.mkdocs.org/user-guide/configuration/#edit_uri", + "type": "string" + }, + "edit_uri_template": { + "description": "The more flexible variant of edit_uri.\nhttps://www.mkdocs.org/user-guide/configuration/#edit_uri_template", + "type": "string" + }, + "site_description": { + "description": "Set the site description. This will add a meta tag to the generated HTML header.\nhttps://www.mkdocs.org/user-guide/configuration/#site_description", + "type": "string" + }, + "site_author": { + "description": "Set the name of the author. This will add a meta tag to the generated HTML header.\nhttps://www.mkdocs.org/user-guide/configuration/#site_author", + "type": "string" + }, + "copyright": { + "description": "Set the copyright information to be included in the documentation by the theme.\nhttps://www.mkdocs.org/user-guide/configuration/#copyright", + "type": "string" + }, + "remote_branch": { + "default": "gh-pages", + "description": "Set the remote branch to commit to when using gh-deploy to deploy to GitHub Pages. This option can be overridden by a command line option in gh-deploy.\nhttps://www.mkdocs.org/user-guide/configuration/#remote_branch", + "type": "string" + }, + "remote_name": { + "default": "origin", + "description": "Set the remote name to push to when using gh-deploy to deploy to GitHub Pages. This option can be overridden by a command line option in gh-deploy.\nhttps://www.mkdocs.org/user-guide/configuration/#remote_name", + "type": "string" + }, + "nav": { + "description": "This setting is used to determine the format and layout of the global navigation for the site.\nhttps://www.mkdocs.org/user-guide/configuration/#nav", + "type": "array", + "items": { + "anyOf": [ + { + "type": "object" + }, + { + "type": "string" + } + ] + } + }, + "theme": { + "description": "Sets the theme and theme specific configuration of your documentation site.\nhttps://www.mkdocs.org/user-guide/configuration/#theme", + "anyOf": [ + { + "type": "object", + "properties": { + "name": { + "default": "mkdocs", + "description": "The string name of a known installed theme.", + "type": "string" + }, + "locale": { + "default": "en", + "description": "A code representing the language of your site.", + "type": "string" + }, + "custom_dir": { + "description": "A directory containing a custom theme. This can either be a relative directory, in which case it is resolved relative to the directory containing your configuration file or it can be an absolute directory path from the root of your local file system.", + "type": "string" + }, + "static_templates": { + "description": "A list of templates to render as static pages. The templates must be located in either the theme's template directory or in the custom_dir defined in the theme configuration.", + "type": "array" + } + } + }, + { + "default": "mkdocs", + "type": "string" + } + ] + }, + "docs_dir": { + "default": "docs", + "description": "The directory containing the documentation source markdown files. This can either be a relative directory, in which case it is resolved relative to the directory containing your configuration file, or it can be an absolute directory path from the root of your local file system.\nhttps://www.mkdocs.org/user-guide/configuration/#docs_dir", + "type": "string" + }, + "site_dir": { + "default": "site", + "description": "The directory where the output HTML and other files are created. This can either be a relative directory, in which case it is resolved relative to the directory containing your configuration file, or it can be an absolute directory path from the root of your local file system.\nhttps://www.mkdocs.org/user-guide/configuration/#site_dir", + "type": "string" + }, + "extra_css": { + "default": [], + "description": "Set a list of CSS files in your docs_dir to be included by the theme. For example, the following example will include the extra.css file within the css subdirectory in your docs_dir.\nhttps://www.mkdocs.org/user-guide/configuration/#extra_css", + "type": "array", + "items": { + "type": "string" + } + }, + "extra_javascript": { + "default": [], + "description": "Set a list of JavaScript files in your docs_dir to be included by the theme. See the example in extra_css for usage.\nhttps://www.mkdocs.org/user-guide/configuration/#extra_javascript", + "type": "array", + "items": { + "type": "string" + } + }, + "extra_templates": { + "default": [], + "description": "Set a list of templates in your docs_dir to be built by MkDocs. To see more about writing templates for MkDocs read the documentation about [custom themes] and specifically the section about the [available variables] to templates. See the example in extra_css for usage.\nhttps://www.mkdocs.org/user-guide/configuration/#extra_templates", + "type": "array", + "items": { + "type": "string" + } + }, + "extra": { + "default": {}, + "description": "A set of key-value pairs, where the values can be any valid YAML construct, that will be passed to the template. This allows for great flexibility when creating custom themes.\nhttps://www.mkdocs.org/user-guide/configuration/#extra", + "type": "object" + }, + "watch": { + "description": "Determines additional directories to watch when running mkdocs serve.\nhttps://www.mkdocs.org/user-guide/configuration/#watch", + "type": "array", + "items": { + "type": "string" + } + }, + "use_directory_urls": { + "default": true, + "description": "This setting controls the style used for linking to pages within the documentation.\nhttps://www.mkdocs.org/user-guide/configuration/#use_directory_urls", + "type": "boolean" + }, + "strict": { + "default": false, + "description": "Determines how warnings are handled. Set to true to halt processing when a warning is raised. Set to false to print a warning and continue processing.\nhttps://www.mkdocs.org/user-guide/configuration/#strict", + "type": "boolean" + }, + "dev_addr": { + "default": "127.0.0.1:8000", + "description": "Determines the address used when running mkdocs serve. Must be of the format IP:PORT.\nhttps://www.mkdocs.org/user-guide/configuration/#dev_addr", + "type": "string" + }, + "markdown_extensions": { + "default": [], + "description": "This setting lets you enable a list of extensions beyond the ones that MkDocs uses by default (meta, toc, tables, and fenced_code).\nhttps://www.mkdocs.org/user-guide/configuration/#markdown_extensions", + "anyOf": [ + { + "type": "array" + }, + { + "type": "object" + } + ] + }, + "hooks": { + "description": "A list of paths to Python scripts (relative to mkdocs.yml) that are loaded and used as plugin instances.\nhttps://www.mkdocs.org/user-guide/configuration/#hooks", + "type": "array" + }, + "plugins": { + "default": ["search"], + "description": "A list of plugins (with optional configuration settings) to use when building the site. See the Plugins documentation for full details.\nhttps://www.mkdocs.org/user-guide/configuration/#plugins", + "anyOf": [ + { + "type": "array" + }, + { + "type": "object" + } + ] + }, + "INHERIT": { + "description": "Define the parent for a configuration file. The path must be relative to the location of the primary file.\nhttps://www.mkdocs.org/user-guide/configuration/#configuration-inheritance", + "type": "string" + } + } + } + }, + "description": "JSON schema for MkDocs configuration file", + "title": "MkDocs Configuration", + "type": "object" +} diff --git a/src/test/mkdocs-1.0/mkdocs-test.yml b/src/test/mkdocs-1.0/mkdocs-test.yml new file mode 100644 index 00000000000..200f4e6c77c --- /dev/null +++ b/src/test/mkdocs-1.0/mkdocs-test.yml @@ -0,0 +1,55 @@ +INHERIT: ../base.yml +site_name: My Docs +site_url: https://example.com/foo/ +repo_url: https://github.com/example/repository/ +repo_name: 'GitHub' +edit_uri: '?query=root/path/docs/' +edit_uri_template: 'blob/main/docs/{path}' +site_description: This is my doc +site_author: Me +copyright: Copyright (c) present, me +remote_branch: gh-pages +remote_name: origin +nav: + - Home: '../' + - 'index.md' + - 'about.md' + - 'Issue Tracker': 'https://example.com/' + - 'User Guide': 'user-guide.md' + - 'Bug Tracker': '/bugs/' +theme: + name: mkdocs + locale: en + custom_dir: my_theme_customizations/ + static_templates: + - sitemap.html + include_sidebar: false +extra_css: + - css/extra.css + - css/second_extra.css +extra_javascript: + - js/extra.js + - js/second_extra.js +extra_templates: + - template.extra + - template.second_extra +extra: + version: 1.0 +watch: + - directory_a + - directory_b +use_directory_urls: true +strict: false +dev_addr: 127.0.0.1:8000 +markdown_extensions: + - smarty + - toc: + permalink: true + - sane_lists +hooks: + - my_hooks.py +plugins: + - search: + - your_other_plugin: + option1: value + option2: other value