| Name | check-mkdocs JSON |
| Version |
1.2.0
JSON |
| download |
| home_page | https://rodrigogonzalez.github.io/check-mkdocs/ |
| Summary | Simple check/command-line tool that parses, validates and loads configuration, builds the mkdocs project documentation, and serves it via a web server |
| upload_time | 2023-08-22 23:03:58 |
| maintainer | |
| docs_url | None |
| author | Rodrigo Gonzalez |
| requires_python | >=3.8,<4.0 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# check-mkdocs
Check if MkDocs is configured correctly
This is a simple .pre-commit-config.yaml hook to check if MkDocs
is configured correctly.
## Installation via Pip
You can install this tool via pip:
```shell
pip install check-mkdocs
```
### Local Installation
This tool is packaged with Poetry. To install it, you can clone the
repository and use Poetry to install the dependencies:
```shell
git clone https://github.com/RodrigoGonzalez/check-mkdocs.git
cd check-mkdocs
poetry install
```
## Features
- Validates the MkDocs configuration file (default is `mkdocs.yml`).
- Builds the MkDocs project documentation via `mkdocs build`.
- Checks the built documentation via `mkdocs serve`.
- Can be used as a pre-commit hook.
- Optionally, it can generate a build of the MkDocs documentation.
Documentation: https://rodrigogonzalez.github.io/check-mkdocs/
## Pre-Commit Usage
Add this to your `.pre-commit-config.yaml`, where `mkdocs.yml`
is the name of your MkDocs YAML configuration file:
```yaml
repos:
- repo: https://github.com/RodrigoGonzalez/check-mkdocs
rev: v1.2.0
hooks:
- id: check-mkdocs
name: check-mkdocs
args: ["--config", "mkdocs.yml"] # Optional, mkdocs.yml is the default
# If you have additional plugins or libraries that are not included in check-mkdocs, add them here
additional_dependencies: ['mkdocs-material']
```
## Command-Line Usage
To run this hook, you can use the following command:
```shell
check-mkdocs --config=mkdocs.yml
```
This works as well:
```shell
check-mkdocs mkdocs.yml
```
And if `mkdocs.yml` is the name of your MkDocs YAML
configuration file, this works too:
```shell
check-mkdocs
```
These commands will validate the MkDocs configuration
file, build the project documentation, and start the
server. If there's an error in any of these steps, the
tool will print an error message and return an error code.
### The `--generate-build` Argument
The `--generate-build` argument is a command-line flag that
you can use to instruct the check_mkdocs tool to generate a
build of the MkDocs documentation. This argument is
optional, and its default value is False, which means that
by default, the tool will not generate a build.
When you provide this argument, the tool will call the
build function from mkdocs.commands.build with the loaded
configuration. This function will build the project
documentation and place the built documentation in the
`site_dir` directory specified in the configuration. If the
`site_dir` directory is not specified in the configuration,
the tool will use the MkDocs default location as the
`site_dir` (i.e., `site/`).
Here's how you can use this argument:
```shell
check-mkdocs --config=mkdocs.yml --generate-build
```
This command will validate the MkDocs configuration file,
build the project documentation, and start the server. If
there's an error in any of these steps, the tool will print
an error message and return an error code.
## Known Issues
### Missing MkDocs Plugins
Given the enormous number of plugins available for MkDocs,
it's possible that some plugins are not included in this
tool. In this case you will see an error message similar to
this:
```shell
check-mkdocs.............................................................Failed
- hook id: check-mkdocs
- exit code: 1
Config value 'theme': Unrecognised theme name: 'material'. The available installed themes are: mkdocs, readthedocs
Config value 'markdown_extensions': Failed to load extension 'pymdownx.snippets'.
ModuleNotFoundError: No module named 'pymdownx'
Config value 'plugins': The "mkdocstrings" plugin is not installed
make: *** [pre-commit] Error 1
```
If you have additional plugins or libraries that are not
included in check-mkdocs, add them here:
```yaml
repos:
- repo: https://github.com/RodrigoGonzalez/check-mkdocs
hooks:
- id: check-mkdocs
# If you have additional plugins or libraries that are not included in check-mkdocs, add them here
additional_dependencies: ['mkdocs-material', 'mkdocstrings']
```
Raw data
{
"_id": null,
"home_page": "https://rodrigogonzalez.github.io/check-mkdocs/",
"name": "check-mkdocs",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Rodrigo Gonzalez",
"author_email": "r@rodrigo-gonzalez.com",
"download_url": "https://files.pythonhosted.org/packages/ee/4e/fb199827ceda2affab3a2080014ba7b0e941875b457edccc38d946fa01ac/check_mkdocs-1.2.0.tar.gz",
"platform": null,
"description": "# check-mkdocs\nCheck if MkDocs is configured correctly\n\nThis is a simple .pre-commit-config.yaml hook to check if MkDocs\nis configured correctly.\n\n## Installation via Pip\n\nYou can install this tool via pip:\n\n```shell\npip install check-mkdocs\n```\n\n### Local Installation\n\nThis tool is packaged with Poetry. To install it, you can clone the\nrepository and use Poetry to install the dependencies:\n\n```shell\ngit clone https://github.com/RodrigoGonzalez/check-mkdocs.git\ncd check-mkdocs\npoetry install\n```\n\n## Features\n\n- Validates the MkDocs configuration file (default is `mkdocs.yml`).\n- Builds the MkDocs project documentation via `mkdocs build`.\n- Checks the built documentation via `mkdocs serve`.\n- Can be used as a pre-commit hook.\n- Optionally, it can generate a build of the MkDocs documentation.\n\nDocumentation: https://rodrigogonzalez.github.io/check-mkdocs/\n\n## Pre-Commit Usage\n\nAdd this to your `.pre-commit-config.yaml`, where `mkdocs.yml`\nis the name of your MkDocs YAML configuration file:\n\n```yaml\nrepos:\n - repo: https://github.com/RodrigoGonzalez/check-mkdocs\n rev: v1.2.0\n hooks:\n - id: check-mkdocs\n name: check-mkdocs\n args: [\"--config\", \"mkdocs.yml\"] # Optional, mkdocs.yml is the default\n # If you have additional plugins or libraries that are not included in check-mkdocs, add them here\n additional_dependencies: ['mkdocs-material']\n```\n\n## Command-Line Usage\n\nTo run this hook, you can use the following command:\n\n```shell\ncheck-mkdocs --config=mkdocs.yml\n```\n\nThis works as well:\n\n```shell\ncheck-mkdocs mkdocs.yml\n```\n\nAnd if `mkdocs.yml` is the name of your MkDocs YAML\nconfiguration file, this works too:\n\n```shell\ncheck-mkdocs\n```\n\nThese commands will validate the MkDocs configuration\nfile, build the project documentation, and start the\nserver. If there's an error in any of these steps, the\ntool will print an error message and return an error code.\n\n### The `--generate-build` Argument\n\nThe `--generate-build` argument is a command-line flag that\nyou can use to instruct the check_mkdocs tool to generate a\nbuild of the MkDocs documentation. This argument is\noptional, and its default value is False, which means that\nby default, the tool will not generate a build.\n\nWhen you provide this argument, the tool will call the\nbuild function from mkdocs.commands.build with the loaded\nconfiguration. This function will build the project\ndocumentation and place the built documentation in the\n`site_dir` directory specified in the configuration. If the\n`site_dir` directory is not specified in the configuration,\nthe tool will use the MkDocs default location as the\n`site_dir` (i.e., `site/`).\n\nHere's how you can use this argument:\n\n```shell\ncheck-mkdocs --config=mkdocs.yml --generate-build\n```\n\nThis command will validate the MkDocs configuration file,\nbuild the project documentation, and start the server. If\nthere's an error in any of these steps, the tool will print\nan error message and return an error code.\n\n## Known Issues\n\n### Missing MkDocs Plugins\n\nGiven the enormous number of plugins available for MkDocs,\nit's possible that some plugins are not included in this\ntool. In this case you will see an error message similar to\nthis:\n\n```shell\ncheck-mkdocs.............................................................Failed\n- hook id: check-mkdocs\n- exit code: 1\n\nConfig value 'theme': Unrecognised theme name: 'material'. The available installed themes are: mkdocs, readthedocs\nConfig value 'markdown_extensions': Failed to load extension 'pymdownx.snippets'.\nModuleNotFoundError: No module named 'pymdownx'\nConfig value 'plugins': The \"mkdocstrings\" plugin is not installed\n\nmake: *** [pre-commit] Error 1\n```\n\nIf you have additional plugins or libraries that are not\nincluded in check-mkdocs, add them here:\n\n```yaml\nrepos:\n - repo: https://github.com/RodrigoGonzalez/check-mkdocs\n hooks:\n - id: check-mkdocs\n # If you have additional plugins or libraries that are not included in check-mkdocs, add them here\n additional_dependencies: ['mkdocs-material', 'mkdocstrings']\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple check/command-line tool that parses, validates and loads configuration, builds the mkdocs project documentation, and serves it via a web server",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://rodrigogonzalez.github.io/check-mkdocs/",
"Repository": "https://github.com/RodrigoGonzalez/check-mkdocs/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a81230b7823228f156e85ec786845f2decaae2d256e5024bea56a923d4d0d73b",
"md5": "e76b05c1e8c8ad77994518cd2443c09c",
"sha256": "6abde740e4357a97a75aea0fcf12f654d2777538f9a9d2be5262664439eeb3ae"
},
"downloads": -1,
"filename": "check_mkdocs-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e76b05c1e8c8ad77994518cd2443c09c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 9518,
"upload_time": "2023-08-22T23:03:57",
"upload_time_iso_8601": "2023-08-22T23:03:57.176665Z",
"url": "https://files.pythonhosted.org/packages/a8/12/30b7823228f156e85ec786845f2decaae2d256e5024bea56a923d4d0d73b/check_mkdocs-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ee4efb199827ceda2affab3a2080014ba7b0e941875b457edccc38d946fa01ac",
"md5": "7a78e3db1eab4feec9d7522837b9371b",
"sha256": "a139d0a0a81feed2bbf1de7bb33a3cedb64b5c6be5d21ce7ff452526fdb729a3"
},
"downloads": -1,
"filename": "check_mkdocs-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "7a78e3db1eab4feec9d7522837b9371b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 6478,
"upload_time": "2023-08-22T23:03:58",
"upload_time_iso_8601": "2023-08-22T23:03:58.584973Z",
"url": "https://files.pythonhosted.org/packages/ee/4e/fb199827ceda2affab3a2080014ba7b0e941875b457edccc38d946fa01ac/check_mkdocs-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-22 23:03:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RodrigoGonzalez",
"github_project": "check-mkdocs",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "check-mkdocs"
}
