mkdocs-meta-descriptions-plugin 0.0.2

Generate meta descriptions using the first paragraph in each MkDocs page

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.

⚠️ 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.

Setting up and using the plugin

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 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.

3. Activate the Meta-Data extension in your mkdocs.yml:

   markdown_extensions:
     - meta
   

Read more about using MkDocs plugins.