Skip to content

Commit

Permalink
Add mkdocs schema (#1) (#2768)
Browse files Browse the repository at this point in the history 
* Add mkdocs schema (#1)

* Added mkdocs schema

* Added test for mkdocs-1.0

* Rename mkdocs.yml to mkdocs-test.yml

* Added mkdocs-1.0 to catalog.json

* Insert final new line to mkdocs-1.0.json

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update mkdocs-1.0.json

`Error: strict mode: missing type "object" for keyword "properties" at "#/definitions/coreProperties" (strictTypes)`

* Update mkdocs-1.0.json

`Error: strict mode: use allowUnionTypes to allow union type keyword at "#/definitions/coreProperties/properties/nav/items" (strictTypes)`

* Update mkdocs-1.0.json

`Error: strict mode: missing type "object" for keyword "required" at "#/allOf/1" (strictTypes)`

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
  • Loading branch information
@squid233 @pre-commit-ci
squid233 and pre-commit-ci[bot] authored Jan 30, 2023
1 parent 500d7a8 commit 1fccae0
Show file tree
Hide file tree
Showing 3 changed files with 267 additions and 0 deletions.
6 changes: 6 additions & 0 deletions src/api/json/catalog.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
206 changes: 206 additions & 0 deletions src/schemas/json/mkdocs-1.0.json
View file
Original file line number Diff line number Diff line change
@@ -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"
}
55 changes: 55 additions & 0 deletions src/test/mkdocs-1.0/mkdocs-test.yml
View file
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 1fccae0

Please sign in to comment.