prcr/mkdocs-meta-descriptions-plugin

📑 Generate meta descriptions from the first paragraphs in your MkDocs pages

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.

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 as a fallback.

Setting up and using the plugin

⚠️ Important: to use this plugin, you must either customize your existing theme to include the value of page.meta.description in the HTML element <meta name="description" content="...">, or use an MkDocs theme that already does this by default. I recommend using the excellent Material theme.

To set up and use the plugin:

1. Install the plugin using pip:

   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:

   plugins:
     - search
     - meta-descriptions

   Note: If you didn't have a plugins declaration in your mkdocs.yml file before this step, you'll likely also want to add the search plugin. This is because MkDocs enables the search plugin by default when there is no plugins declaration, but now you have to enable it explicitly.

Configuring the plugin

Use the following options to configure the behavior of the plugin:

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.

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.

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.

See also

Read more about using MkDocs plugins.

mkdocs-meta-descriptions-plugin's Issues

Incorrect use of <p> text inside <div> as the meta description

Describe the bug
A clear and concise description of what the bug is.

The plugin incorrectly considers the paragraph that contains the title of the admonition as the meta description for a page:

<h1 id="title">Title</h1>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Note text</p>
</div>
<p>This should be used as the meta description</p>

To Reproduce
The list of steps to reproduce the behavior.

Expected behavior
A clear and concise description of what you expected to happen.

The plugin should only consider for the meta description paragraphs that are siblings to the <h1> tag. Decide if in these cases the <div> can be ignored and the next <p> is used, or if no meta description should be deduced from the page content.

Additional context
Add any other context about the problem here.

I identified the issue on this page.

Use site_url to build page URLs in exported CSV file

If site_url is defined, use it to build the page URLs before writing them to the meta-descriptions.csv file.

Review plugin to take into account the changes from MkDocs 1.4.0

Review the MkDocs 1.4.0 changelog and reflect any relevant changes on the plugin:

https://github.com/mkdocs/mkdocs/releases/tag/1.4.0

Trim first paragraph text

Trim the text of the first paragraph found, and check the length of the text only after trimming.

Review code to take into account the changes from MkDocs 1.4.0

Go through the breaking changes from the MkDocs 1.4.0 changelog and make any necessary changes to the code to ensure that it is compatible with MkDocs 1.4.0.

Supersedes #193.

Correctly handle double quotes when setting meta descriptions

If the first paragraph of a page includes double quotes, the plugin should remove or escape them so that they don't break the description attribute of the <meta> HTML element.

Improve detection of the first paragraph when text of first <p> is empty

There are some situations where the text of the first paragraph that is found by the plugin may be empty.

For example:

<p><a href="...">Welcome to the site!</a></p>

<p><img src="..."/></p>

Perhaps in situations like this the plugin could try to find a sibling paragraph that does include text.

Trim meta descriptions if they exceed the maximum length

I suggest using the max variable to trim meta descriptions that have more characters than the value of the variable

Error when using plugin with Material for MkDocs

Hi,
I get this error when trying to use the plugin with Material for MkDocs. What am I doing wrong?

Solve deprecation warning for collections.abc

Solve the deprecation warning for collections.abc:

$ mkdocs build
INFO     -  DeprecationWarning: Using or importing the ABCs from 'collections' instead of from
            'collections.abc' is deprecated since Python 3.3, and in 3.10 it will stop working
              File "/usr/lib/python3/dist-packages/html5lib/_trie/_base.py", line 3, in <module>
                from collections import Mapping
              File "/usr/lib/python3.8/collections/__init__.py", line 49, in __getattr__
                warnings.warn("Using or importing the ABCs from 'collections' instead "
INFO     -  Cleaning site directory

Review code to take into account the changes from MkDocs 1.5.0

Go through the breaking changes from the MkDocs 1.5.0 changelog and make any necessary changes to the code to ensure that it is compatible with MkDocs 1.5.0.

In particular, some WARNING log messages are now being output with the DEBUG log level instead.

Cc: @autopilot