Add per-file overrides using field lists

README.md

@@ -37,7 +37,7 @@ Users hosting documentation on Read The Docs *do not* need to set any of the fol
     * This sets the ogp type attribute, for more information on the types available please take a look at https://ogp.me/#types. By default it is set to `website`, which should be fine for most use cases.
 * `ogp_custom_meta_tags`
     * This is not required. List of custom html snippets to insert.
-
+    
 ## Example Config
 
 ### Simple Config
@@ -60,3 +60,32 @@ ogp_custom_meta_tags = [
 ]
 
 ```
+
+## Per Page Overrides
+[Field lists](https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html) are used to allow you to override certain settings on each page.
+
+Make sure you place the fields at the very start of the document such that Sphinx will pick them up and also won't build them into the html.
+
+### Overrides
+
+* `:ogp-description-length:`
+  * Configure the amount of characters to grab for the description of the page. If the value isn't a number it will fall back to `ogp_description_length`.
+* `:ogp-description:`
+  * Lets you override the description of the page.
+* `:ogp-title:`
+  * Lets you override the title of the page.
+* `:ogp-type:`
+  * Override the type of the page, for the list of available types take a look at https://ogp.me/#types.
+* `:ogp-image:`
+  * Set the image for the page.
+* `:ogp-image-alt:`
+  * Will be ignored if the image isn't set with the above field, if the image is set, sets the alt text for it.
+
+### Example
+Remember that the fields **must** be placed at the very start of the file. You can verify Sphinx has picked up the fields if they aren't shown in the final html file.
+
+```rst
+:ogp-description: New description
+:ogp-image: http://example.org/image.png
+:ogp-image-alt: Example Image
+```

sphinxext/opengraph/__init__.py

@@ -29,6 +29,8 @@
 
 
 def make_tag(property: str, content: str) -> str:
+    # Parse quotation, so they won't break html tags if smart quotes are disabled
+    content = content.replace('"', """)
     return f'<meta property="{property}" content="{content}" />\n  '
 
 
@@ -38,10 +40,17 @@ def get_tags(
     doctree: nodes.document,
     config: Dict[str, Any],
 ) -> str:
+    # Get field lists for per-poge overrides
+    fields = context["meta"]
+    if fields is None:
+        fields = {}
 
     # Set length of description
     try:
-        desc_len = int(config["ogp_description_length"])
+        try:
+            desc_len = int(fields["ogp-description-length"])
+        except (ValueError, KeyError):
+            desc_len = int(config["ogp_description_length"])
     except ValueError:
         desc_len = DEFAULT_DESCRIPTION_LENGTH
 
@@ -50,15 +59,24 @@ def get_tags(
     title_excluding_html = get_title(context["title"], skip_html_tags=True)
 
     # Parse/walk doctree for metadata (tag/description)
-    description = get_description(doctree, desc_len, [title, title_excluding_html])
+    if "ogp-description" in fields:
+        description = fields["ogp-description"]
+    else:
+        description = get_description(doctree, desc_len, [title, title_excluding_html])
 
     tags = "\n  "
 
     # title tag
-    tags += make_tag("og:title", title)
+    tags += make_tag(
+        "og:title", title if "ogp-title" not in fields else fields["ogp-title"]
+    )
 
     # type tag
-    tags += make_tag("og:type", config["ogp_type"])
+    tags += make_tag(
+        "og:type",
+        config["ogp_type"] if "ogp-type" not in fields else fields["ogp-type"],
+    )
+
     if os.getenv("READTHEDOCS") and config["ogp_site_url"] is None:
         # readthedocs uses html_baseurl for sphinx > 1.8
         parse_result = urlparse(config["html_baseurl"])
@@ -86,7 +104,11 @@ def get_tags(
     tags += make_tag("og:url", page_url)
 
     # site name tag
-    site_name = config["ogp_site_name"]
+    site_name = (
+        config["ogp_site_name"]
+        if "ogp-site-name" not in fields
+        else fields["ogp-site-name"]
+    )
     if site_name:
         tags += make_tag("og:site_name", site_name)
 
@@ -96,9 +118,14 @@ def get_tags(
 
     # image tag
     # Get basic values from config
-    image_url = config["ogp_image"]
-    ogp_use_first_image = config["ogp_use_first_image"]
-    ogp_image_alt = config["ogp_image_alt"]
+    if "ogp-image" in fields:
+        image_url = fields["ogp-image"]
+        ogp_use_first_image = False
+        ogp_image_alt = fields["ogp-image-alt"] if "ogp-image-alt" in fields else None
+    else:
+        image_url = config["ogp_image"]
+        ogp_use_first_image = config["ogp_use_first_image"]
+        ogp_image_alt = config["ogp_image_alt"]
 
     if ogp_use_first_image:
         first_image = doctree.next_node(nodes.image)

sphinxext/opengraph/descriptionparser.py

@@ -18,7 +18,7 @@ def __init__(
 
         # Hack to prevent requirement for the doctree to be passed in.
         # It's only used by doctree.walk(...) to print debug messages.
-        if document == None:
+        if document is None:
 
             class document_cls:
                 class reporter:
@@ -124,5 +124,4 @@ def get_description(
 
     mcv = DescriptionParser(description_length, known_titles, document)
     doctree.walkabout(mcv)
-    # Parse quotation so they won't break html tags if smart quotes are disabled
-    return mcv.description.replace('"', """)
+    return mcv.description

tests/roots/test-overrides-complex/conf.py

@@ -0,0 +1,10 @@
+extensions = ["sphinxext.opengraph"]
+
+master_doc = "index"
+exclude_patterns = ["_build"]
+
+html_theme = "basic"
+
+ogp_site_name = "Example's Docs!"
+ogp_site_url = "http://example.org/"
+ogp_image_alt = "Example Alt Text"

tests/roots/test-overrides-complex/index.rst

@@ -0,0 +1,6 @@
+:ogp-description-length: 10
+:ogp-image: img/sample.jpg
+:ogp-image-alt: Overridden Alt Text
+Lorem Ipsum
+===========
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse at lorem ornare, fringilla massa nec, venenatis mi. Donec erat sapien, tincidunt nec rhoncus nec, scelerisque id diam. Orci varius natoque penatibus et magnis dis parturient mauris.

tests/roots/test-overrides-simple/conf.py

@@ -0,0 +1,11 @@
+extensions = ["sphinxext.opengraph"]
+
+master_doc = "index"
+exclude_patterns = ["_build"]
+
+html_theme = "basic"
+
+ogp_site_name = "Example's Docs!"
+ogp_site_url = "http://example.org/"
+ogp_image = "http://example.org/image.png"
+ogp_type = "book"

tests/roots/test-overrides-simple/index.rst

@@ -0,0 +1,7 @@
+:ogp-description: Overridden description
+:ogp-title: Overridden Title
+:ogp-type: article
+:ogp-image: http://example.org/overridden-image.png
+Lorem Ipsum
+===========
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse at lorem ornare, fringilla massa nec, venenatis mi. Donec erat sapien, tincidunt nec rhoncus nec, scelerisque id diam. Orci varius natoque penatibus et magnis dis parturient mauris.

tests/test_options.py

@@ -160,6 +160,26 @@ def test_quotation_marks(og_meta_tags):
     )
 
 
+@pytest.mark.sphinx("html", testroot="overrides-simple")
+def test_overrides_simple(og_meta_tags):
+    assert get_tag_content(og_meta_tags, "description") == "Overridden description"
+    assert get_tag_content(og_meta_tags, "title") == "Overridden Title"
+    assert get_tag_content(og_meta_tags, "type") == "article"
+    assert (
+        get_tag_content(og_meta_tags, "image")
+        == "http://example.org/overridden-image.png"
+    )
+    # Make sure alt text still works even when overriding the image
+    assert get_tag_content(og_meta_tags, "image:alt") == "Example's Docs!"
+
+
+@pytest.mark.sphinx("html", testroot="overrides-complex")
+def test_overrides_complex(og_meta_tags):
+    assert len(get_tag_content(og_meta_tags, "description")) == 10
+    assert get_tag_content(og_meta_tags, "image") == "http://example.org/img/sample.jpg"
+    assert get_tag_content(og_meta_tags, "image:alt") == "Overridden Alt Text"
+
+
 # use same as simple, as configuration is identical to overriden
 @pytest.mark.sphinx("html", testroot="simple")
 def test_rtd_override(app: Sphinx, monkeypatch):