Merge 9ed0eb1c0c into 6f10e8f2b6

docs/changelog.rst

@@ -24,6 +24,7 @@ Release history
 4.11.0 - 2025-01-15
 ===================
 
+- Add HEADING_METADATA feature for Markdown title extraction, allowing metadata to be extracted from headings based on configurable patterns and level mappings
 - Add setting to selectively omit Typogrify filters `(#3439) <https://github.com/getpelican/pelican/pull/3439>`_
 - Add more blocks to the Simple theme’s base template, making it easier to create new themes by inheriting from the Simple theme `(#3405) <https://github.com/getpelican/pelican/pull/3405>`_
 - Fix auto-reload behavior upon changes to the theme, content or settings. Make default ``IGNORE_FILES`` recursively ignore all hidden files as well as the `default filters <https://watchfiles.helpmanual.io/api/filters/#watchfiles.DefaultFilter.ignore_dirs>`_ from ``watchfiles.DefaultFilter``. `(#3441) <https://github.com/getpelican/pelican/pull/3441>`_

docs/content.rst

@@ -175,7 +175,38 @@ example, if you would like to extract both the date and the slug, you could set
 something like: ``'(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)'``
 
 Please note that the metadata available inside your files takes precedence over
-the metadata extracted from the filename.
+metadata extracted from the filename.
+
+Metadata extraction from Markdown headings
+==========================================
+
+For Markdown files, you can also extract metadata from headings using the
+``HEADING_METADATA`` setting. This is particularly useful for articles where you
+want to use the first heading as the title without explicitly declaring it in
+the metadata section.
+
+When ``HEADING_METADATA`` is enabled, Pelican can extract metadata from headings
+using either level mappings or custom regex patterns. This allows Markdown files
+like::
+
+    Date: 2023-12-01
+    Category: tech
+
+    # My Article Title
+
+    Content goes here...
+
+This allows their titles to be extracted automatically without requiring
+explicit ``Title:`` metadata. Note that Markdown files must begin with the
+metadata block, and headings should follow it.
+
+The headings used for metadata extraction are automatically removed from the
+content to avoid duplication in the output.
+
+See the :ref:`HEADING_METADATA <settings/HEADING_METADATA>`,
+:ref:`HEADING_METADATA_MAP <settings/HEADING_METADATA_MAP>`, and
+:ref:`HEADING_METADATA_PATTERNS <settings/HEADING_METADATA_PATTERNS>` settings
+in the documentation for configuration options.
 
 Pages
 =====

docs/settings.rst

@@ -986,8 +986,71 @@ Metadata
            "static/robots.txt": {"path": "robots.txt"},
        }
 
-   .. _group name notation:
-      https://docs.python.org/3/library/re.html#regular-expression-syntax
+.. data:: HEADING_METADATA
+
+   Enable or disable metadata extraction from Markdown headings. When set to
+   ``True``, Pelican will extract metadata from headings according to the
+   ``HEADING_METADATA_MAP`` and ``HEADING_METADATA_PATTERNS`` settings. Pelican
+   removes extracted headings from the content to avoid duplication. The default
+   is ``False``.
+
+.. data:: HEADING_METADATA_MAP
+
+   A mapping of heading levels to metadata field names. This pallows metadata to
+   be extracted from specific heading levels. For example, ``{1: 'title'}`` will
+   map level 1 headings (``# Heading``) to the ``title`` metadata field.
+   Multiple levels can be mapped to different fields. The default is::
+
+       HEADING_METADATA_MAP = {
+           1: 'title',      # # Heading → title
+           2: 'subtitle',   # ## Heading → subtitle
+           3: 'summary',    # ### Heading → summary
+       }
+
+.. data:: HEADING_METADATA_PATTERNS
+
+   Custom regex patterns for extracting metadata from headings. This provides
+   more flexibility than ``HEADING_METADATA_MAP`` by allowing you to match
+   specific heading patterns. The patterns are processed before the level
+   mapping, if both are configured. The default is::
+
+       HEADING_METADATA_PATTERNS = {
+           'title': r'^#\s+(.+)$',
+           'subtitle': r'^##\s+(.+)$',
+           'summary': r'^###\s+(.+)$',
+           'author': r'^###\s+Author[:\s]+(.+)$',
+           'date': r'^###\s+Date[:\s]+(.+)$',
+       }
+
+   Example usage::
+
+       # Enable heading metadata extraction
+       HEADING_METADATA = True
+
+       # Simple title extraction from first level heading
+       HEADING_METADATA_PATTERNS = {
+           'title': r'^#\s+(.+)$'
+       }
+
+       # Or use level mapping instead
+       HEADING_METADATA_MAP = {
+           1: 'title'
+       }
+
+   This allows Markdown files like::
+
+       Date: 2023-12-01
+       Category: tech
+
+       # My Article Title
+
+       Content goes here...
+
+   This allows their titles to be extracted automatically without requiring
+   explicit ``Title:`` metadata.
+
+.. _`group name notation`:
+   https://docs.python.org/3/library/re.html#regular-expression-syntax
 
    The default is ``{}``.