# mkdocs-meta-descriptions-plugin
[](https://github.com/prcr/mkdocs-meta-descriptions-plugin/actions/workflows/test-build-deploy.yml)
[](https://app.codacy.com/gh/prcr/mkdocs-meta-descriptions-plugin/dashboard?utm_source=github.com&utm_medium=referral&utm_content=prcr/mkdocs-meta-descriptions-plugin&utm_campaign=Badge_Grade)
[](https://app.codacy.com/gh/prcr/mkdocs-meta-descriptions-plugin/dashboard?utm_source=github.com&utm_medium=referral&utm_content=prcr/mkdocs-meta-descriptions-plugin&utm_campaign=Badge_Coverage)
[](https://pypi.org/project/mkdocs-meta-descriptions-plugin/)
Use this MkDocs plugin to automatically generate meta descriptions for your pages using the first paragraph of each page. This is useful if you start each page with a short introduction or summary that can be reused as the meta description.
For each page, the plugin:
1. Checks that the page doesn't already have a meta description.
The plugin **doesn't change** any meta descriptions defined explicitly on the [page meta-data](https://www.mkdocs.org/user-guide/writing-your-docs/#meta-data).
2. Tries to find the first paragraph above any `<h2>` to `<h6>` headings.
The plugin only searches for the first paragraph until the start of the first section to ensure that the content is from the "introductory" part of the page.
3. Sets the meta description of the page to the plain text context of the paragraph, stripped of HTML tags.
If the page doesn't have a meta description defined manually by you nor automatically by the plugin, MkDocs sets the meta description of the page to the value of your [`site_description`](https://www.mkdocs.org/user-guide/configuration/#site_description) as a fallback.
## Setting up and using the plugin
> ⚠️ **Important:** to use this plugin, you must either [customize your existing theme](https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks) to include the value of [`page.meta.description`](https://www.mkdocs.org/user-guide/custom-themes/#pagemeta) in the HTML element `<meta name="description" content="...">`, or use an [MkDocs theme](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes) that already does this by default. I recommend using the excellent [Material theme](https://github.com/squidfunk/mkdocs-material).
To set up and use the plugin:
1. Install the plugin using pip:
```bash
pip install mkdocs-meta-descriptions-plugin
```
Depending on your project, you may also need to add the plugin as a dependency on your `requirements.txt` file.
2. Activate the plugin in your `mkdocs.yml`:
```yaml
plugins:
- search
- meta-descriptions
```
> **Note:** If you have no `plugins` entry in your `mkdocs.yml` file yet, you'll likely also want to add the `search` plugin. MkDocs enables it by default if there is no `plugins` entry set, but now you have to enable it explicitly.
## Configuring the plugin
Use the following options to configure the behavior of the plugin:
```yaml
plugins:
- meta-descriptions:
export_csv: false
quiet: false
enable_checks: false
min_length: 50
max_length: 160
trim: false
```
### `export_csv`
If `true`, the plugin exports the meta descriptions of all Markdown pages to the CSV file `<site_dir>/meta-descriptions.csv`. The default is `false`.
This is useful to review and keep track of all the meta descriptions for your pages, especially if you're maintaining a big site.
### `quiet`
If `true`, the plugin logs messages of level `INFO` using the level `DEBUG` instead. The default is `false`.
Enable this option to have a cleaner MkDocs console output. You can still see all logs by running MkDocs with the `--verbose` flag.
### `enable_checks`
If `true`, the plugin outputs a warning for each page that will have an empty or default meta description, as well as for each meta description shorter than `min_length` or longer than `max_length`. The default is `false`.
Enable this option if you want to make sure that all pages have a meta description and that each meta description follows general SEO best practices.
### `min_length`
Minimum number of characters that each meta description should have. The default is 50 characters, based on [these general recommendations](https://moz.com/learn/seo/meta-description).
Make sure that you set `enable_checks: true` for this option to have an effect.
### `max_length`
Maximum number of characters that each meta description should have. The default is 160 characters, based on [these general recommendations](https://moz.com/learn/seo/meta-description).
Make sure that you set `enable_checks: true` or `trim: true` for this option to have an effect.
### `trim`
If `true`, the plugin trims meta descriptions coming from the first paragraph of the pages to include at most `max_length` characters.
Note that this option doesn't change any meta descriptions defined explicitly on the [page meta-data](https://www.mkdocs.org/user-guide/writing-your-docs/#meta-data).
## See also
Read more about [using MkDocs plugins](http://www.mkdocs.org/user-guide/plugins/).
Raw data
{
"_id": null,
"home_page": "https://github.com/prcr/mkdocs-meta-descriptions-plugin",
"name": "mkdocs-meta-descriptions-plugin",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": "",
"keywords": "mkdocs meta description seo paragraph",
"author": "Paulo Ribeiro",
"author_email": "paulo@diffraction.pt",
"download_url": "https://files.pythonhosted.org/packages/e3/1c/2228745b4831422c126cf98ba2fafad03676027926196dc8950ee39995fe/mkdocs-meta-descriptions-plugin-3.0.0.tar.gz",
"platform": null,
"description": "# mkdocs-meta-descriptions-plugin\n\n[](https://github.com/prcr/mkdocs-meta-descriptions-plugin/actions/workflows/test-build-deploy.yml)\n[](https://app.codacy.com/gh/prcr/mkdocs-meta-descriptions-plugin/dashboard?utm_source=github.com&utm_medium=referral&utm_content=prcr/mkdocs-meta-descriptions-plugin&utm_campaign=Badge_Grade)\n[](https://app.codacy.com/gh/prcr/mkdocs-meta-descriptions-plugin/dashboard?utm_source=github.com&utm_medium=referral&utm_content=prcr/mkdocs-meta-descriptions-plugin&utm_campaign=Badge_Coverage)\n[](https://pypi.org/project/mkdocs-meta-descriptions-plugin/)\n\nUse this MkDocs plugin to automatically generate meta descriptions for your pages using the first paragraph of each page. This is useful if you start each page with a short introduction or summary that can be reused as the meta description.\n\n\n\nFor each page, the plugin:\n\n1. Checks that the page doesn't already have a meta description.\n\n The plugin **doesn't change** any meta descriptions defined explicitly on the [page meta-data](https://www.mkdocs.org/user-guide/writing-your-docs/#meta-data).\n\n2. Tries to find the first paragraph above any `<h2>` to `<h6>` headings.\n\n The plugin only searches for the first paragraph until the start of the first section to ensure that the content is from the \"introductory\" part of the page.\n\n3. Sets the meta description of the page to the plain text context of the paragraph, stripped of HTML tags.\n\nIf the page doesn't have a meta description defined manually by you nor automatically by the plugin, MkDocs sets the meta description of the page to the value of your [`site_description`](https://www.mkdocs.org/user-guide/configuration/#site_description) as a fallback.\n\n## Setting up and using the plugin\n\n> \u26a0\ufe0f **Important:** to use this plugin, you must either [customize your existing theme](https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks) to include the value of [`page.meta.description`](https://www.mkdocs.org/user-guide/custom-themes/#pagemeta) in the HTML element `<meta name=\"description\" content=\"...\">`, or use an [MkDocs theme](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes) that already does this by default. I recommend using the excellent [Material theme](https://github.com/squidfunk/mkdocs-material).\n\nTo set up and use the plugin:\n\n1. Install the plugin using pip:\n\n ```bash\n pip install mkdocs-meta-descriptions-plugin\n ```\n\n Depending on your project, you may also need to add the plugin as a dependency on your `requirements.txt` file.\n\n2. Activate the plugin in your `mkdocs.yml`:\n\n ```yaml\n plugins:\n - search\n - meta-descriptions\n ```\n\n > **Note:** If you have no `plugins` entry in your `mkdocs.yml` file yet, you'll likely also want to add the `search` plugin. MkDocs enables it by default if there is no `plugins` entry set, but now you have to enable it explicitly.\n\n## Configuring the plugin\n\nUse the following options to configure the behavior of the plugin:\n\n```yaml\nplugins:\n - meta-descriptions:\n export_csv: false\n quiet: false\n enable_checks: false\n min_length: 50\n max_length: 160\n trim: false\n```\n\n### `export_csv`\n\nIf `true`, the plugin exports the meta descriptions of all Markdown pages to the CSV file `<site_dir>/meta-descriptions.csv`. The default is `false`.\n\nThis is useful to review and keep track of all the meta descriptions for your pages, especially if you're maintaining a big site.\n\n### `quiet`\n\nIf `true`, the plugin logs messages of level `INFO` using the level `DEBUG` instead. The default is `false`.\n\nEnable this option to have a cleaner MkDocs console output. You can still see all logs by running MkDocs with the `--verbose` flag.\n\n### `enable_checks`\n\nIf `true`, the plugin outputs a warning for each page that will have an empty or default meta description, as well as for each meta description shorter than `min_length` or longer than `max_length`. The default is `false`.\n\nEnable this option if you want to make sure that all pages have a meta description and that each meta description follows general SEO best practices.\n\n### `min_length`\n\nMinimum number of characters that each meta description should have. The default is 50 characters, based on [these general recommendations](https://moz.com/learn/seo/meta-description).\n\nMake sure that you set `enable_checks: true` for this option to have an effect.\n\n### `max_length`\n\nMaximum number of characters that each meta description should have. The default is 160 characters, based on [these general recommendations](https://moz.com/learn/seo/meta-description).\n\nMake sure that you set `enable_checks: true` or `trim: true` for this option to have an effect.\n\n### `trim`\n\nIf `true`, the plugin trims meta descriptions coming from the first paragraph of the pages to include at most `max_length` characters.\n\nNote that this option doesn't change any meta descriptions defined explicitly on the [page meta-data](https://www.mkdocs.org/user-guide/writing-your-docs/#meta-data).\n\n## See also\n\nRead more about [using MkDocs plugins](http://www.mkdocs.org/user-guide/plugins/).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate meta descriptions from the first paragraphs in your MkDocs pages",
"version": "3.0.0",
"project_urls": {
"Homepage": "https://github.com/prcr/mkdocs-meta-descriptions-plugin"
},
"split_keywords": [
"mkdocs",
"meta",
"description",
"seo",
"paragraph"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0e6be0a2d1cf556f107945b904d2f28ef58059fb3780356664be913b8916202e",
"md5": "a8429bef949b7a09370c9222a9d6955b",
"sha256": "93beb60b731057f5a863d1b8059615a2320db4183c3999a941c1c9ee14923949"
},
"downloads": -1,
"filename": "mkdocs_meta_descriptions_plugin-3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a8429bef949b7a09370c9222a9d6955b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 8688,
"upload_time": "2023-12-06T16:49:10",
"upload_time_iso_8601": "2023-12-06T16:49:10.336042Z",
"url": "https://files.pythonhosted.org/packages/0e/6b/e0a2d1cf556f107945b904d2f28ef58059fb3780356664be913b8916202e/mkdocs_meta_descriptions_plugin-3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e31c2228745b4831422c126cf98ba2fafad03676027926196dc8950ee39995fe",
"md5": "0cbc9c1bea2e4f69c7d5d1805aeff555",
"sha256": "79c9ebb0c34e11312e32467cb02225d39a9ee84192c07e71fcc8708dde502feb"
},
"downloads": -1,
"filename": "mkdocs-meta-descriptions-plugin-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "0cbc9c1bea2e4f69c7d5d1805aeff555",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 143906,
"upload_time": "2023-12-06T16:49:12",
"upload_time_iso_8601": "2023-12-06T16:49:12.216763Z",
"url": "https://files.pythonhosted.org/packages/e3/1c/2228745b4831422c126cf98ba2fafad03676027926196dc8950ee39995fe/mkdocs-meta-descriptions-plugin-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-06 16:49:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "prcr",
"github_project": "mkdocs-meta-descriptions-plugin",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"lcname": "mkdocs-meta-descriptions-plugin"
}
JSON
