From 297ba8e637e021df6329d6c5b7035187655fc29f Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Mon, 6 Dec 2021 14:07:54 +0200 Subject: [PATCH 01/23] Use field lists to implement per page overrides --- sphinxext/opengraph/__init__.py | 35 ++++++++++++++++++++++++++------- 1 file changed, 28 insertions(+), 7 deletions(-) diff --git a/sphinxext/opengraph/__init__.py b/sphinxext/opengraph/__init__.py index 00ccdcf..3112e5e 100644 --- a/sphinxext/opengraph/__init__.py +++ b/sphinxext/opengraph/__init__.py @@ -38,10 +38,15 @@ def get_tags( doctree: nodes.document, config: Dict[str, Any], ) -> str: + # Get field lists for per-poge overrides + fields = context["meta"] # 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,7 +55,10 @@ 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 " @@ -58,7 +66,11 @@ def get_tags( tags += make_tag("og:title", 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 +98,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 +112,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) From b56c4c59194b2e2c1a72afba2ac41f229278ccf7 Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Mon, 6 Dec 2021 14:11:31 +0200 Subject: [PATCH 02/23] Move location where quotes are escaped so that it will work with per page overrides and in general will only happen when it becomes a html tag and starts mattering. --- sphinxext/opengraph/__init__.py | 2 ++ sphinxext/opengraph/descriptionparser.py | 5 ++--- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/sphinxext/opengraph/__init__.py b/sphinxext/opengraph/__init__.py index 3112e5e..6cd18d5 100644 --- a/sphinxext/opengraph/__init__.py +++ b/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'\n ' diff --git a/sphinxext/opengraph/descriptionparser.py b/sphinxext/opengraph/descriptionparser.py index 96c6a5a..a89aa65 100644 --- a/sphinxext/opengraph/descriptionparser.py +++ b/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 From 82299a0f09630fd24c2cd4f2cdb0747a2fd42c82 Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Mon, 6 Dec 2021 14:21:33 +0200 Subject: [PATCH 03/23] Add title override --- sphinxext/opengraph/__init__.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/sphinxext/opengraph/__init__.py b/sphinxext/opengraph/__init__.py index 6cd18d5..81014dd 100644 --- a/sphinxext/opengraph/__init__.py +++ b/sphinxext/opengraph/__init__.py @@ -65,7 +65,9 @@ def get_tags( 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( From 63655fd2900e65cbca98bb26e0c9a014ac3a2fd2 Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Mon, 6 Dec 2021 14:30:26 +0200 Subject: [PATCH 04/23] Add documentation for field lists --- README.md | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 1ab7535..d24977f 100644 --- a/README.md +++ b/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 +``` \ No newline at end of file From 3a8e623cc353adec0da6a4e5e0509b9c9b87a772 Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Mon, 6 Dec 2021 14:50:20 +0200 Subject: [PATCH 05/23] Fix empty field lists from crashing --- sphinxext/opengraph/__init__.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/sphinxext/opengraph/__init__.py b/sphinxext/opengraph/__init__.py index 81014dd..9d659cb 100644 --- a/sphinxext/opengraph/__init__.py +++ b/sphinxext/opengraph/__init__.py @@ -42,6 +42,8 @@ def get_tags( ) -> str: # Get field lists for per-poge overrides fields = context["meta"] + if fields is None: + fields = {} # Set length of description try: From cbdcc0f6449860706cf3d3b7cc164bf5a371b0c0 Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Sun, 12 Dec 2021 15:13:34 +0200 Subject: [PATCH 06/23] Add tests --- tests/roots/test-overrides-complex/conf.py | 10 ++++++++++ tests/roots/test-overrides-complex/index.rst | 6 ++++++ tests/roots/test-overrides-simple/conf.py | 11 +++++++++++ tests/roots/test-overrides-simple/index.rst | 7 +++++++ tests/test_options.py | 20 ++++++++++++++++++++ 5 files changed, 54 insertions(+) create mode 100644 tests/roots/test-overrides-complex/conf.py create mode 100644 tests/roots/test-overrides-complex/index.rst create mode 100644 tests/roots/test-overrides-simple/conf.py create mode 100644 tests/roots/test-overrides-simple/index.rst diff --git a/tests/roots/test-overrides-complex/conf.py b/tests/roots/test-overrides-complex/conf.py new file mode 100644 index 0000000..f03d03c --- /dev/null +++ b/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" diff --git a/tests/roots/test-overrides-complex/index.rst b/tests/roots/test-overrides-complex/index.rst new file mode 100644 index 0000000..a105045 --- /dev/null +++ b/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. diff --git a/tests/roots/test-overrides-simple/conf.py b/tests/roots/test-overrides-simple/conf.py new file mode 100644 index 0000000..fbab6c5 --- /dev/null +++ b/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" diff --git a/tests/roots/test-overrides-simple/index.rst b/tests/roots/test-overrides-simple/index.rst new file mode 100644 index 0000000..478d906 --- /dev/null +++ b/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. diff --git a/tests/test_options.py b/tests/test_options.py index 2f7cb7f..dfdf0aa 100644 --- a/tests/test_options.py +++ b/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): From 00b05ca2ce371bc13406415d319cf3d2184b2bd4 Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Wed, 26 Jan 2022 15:26:29 +0200 Subject: [PATCH 07/23] Refractor to use fields.get to get the values --- sphinxext/opengraph/__init__.py | 27 ++++++--------------------- 1 file changed, 6 insertions(+), 21 deletions(-) diff --git a/sphinxext/opengraph/__init__.py b/sphinxext/opengraph/__init__.py index 9d659cb..9f791ec 100644 --- a/sphinxext/opengraph/__init__.py +++ b/sphinxext/opengraph/__init__.py @@ -47,10 +47,7 @@ def get_tags( # Set length of description try: - try: - desc_len = int(fields["ogp-description-length"]) - except (ValueError, KeyError): - desc_len = int(config["ogp_description_length"]) + desc_len = int(fields.get("ogp-description-length", config["ogp_description_length"])) except ValueError: desc_len = DEFAULT_DESCRIPTION_LENGTH @@ -59,23 +56,15 @@ def get_tags( title_excluding_html = get_title(context["title"], skip_html_tags=True) # Parse/walk doctree for metadata (tag/description) - if "ogp-description" in fields: - description = fields["ogp-description"] - else: - description = get_description(doctree, desc_len, [title, title_excluding_html]) + description = fields.get("ogp-description", get_description(doctree, desc_len, [title, title_excluding_html])) tags = "\n " # title tag - tags += make_tag( - "og:title", title if "ogp-title" not in fields else fields["ogp-title"] - ) + tags += make_tag("og:title", fields.get("ogp-title", title)) # type tag - tags += make_tag( - "og:type", - config["ogp_type"] if "ogp-type" not in fields else fields["ogp-type"], - ) + tags += make_tag("og:type", fields.get("ogp-type", config["ogp_type"])) if os.getenv("READTHEDOCS") and config["ogp_site_url"] is None: # readthedocs uses html_baseurl for sphinx > 1.8 @@ -104,11 +93,7 @@ def get_tags( tags += make_tag("og:url", page_url) # site name tag - site_name = ( - config["ogp_site_name"] - if "ogp-site-name" not in fields - else fields["ogp-site-name"] - ) + site_name = fields.get("ogp-site-name", config["ogp_site_name"]) if site_name: tags += make_tag("og:site_name", site_name) @@ -121,7 +106,7 @@ def get_tags( 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 + ogp_image_alt = fields.get("ogp-image-alt") else: image_url = config["ogp_image"] ogp_use_first_image = config["ogp_use_first_image"] From a72b254188fee6fe45a4ba882699c7ade720707a Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Wed, 26 Jan 2022 16:22:11 +0200 Subject: [PATCH 08/23] Run black --- sphinxext/opengraph/__init__.py | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/sphinxext/opengraph/__init__.py b/sphinxext/opengraph/__init__.py index 9f791ec..cc17601 100644 --- a/sphinxext/opengraph/__init__.py +++ b/sphinxext/opengraph/__init__.py @@ -47,7 +47,9 @@ def get_tags( # Set length of description try: - desc_len = int(fields.get("ogp-description-length", config["ogp_description_length"])) + desc_len = int( + fields.get("ogp-description-length", config["ogp_description_length"]) + ) except ValueError: desc_len = DEFAULT_DESCRIPTION_LENGTH @@ -56,7 +58,10 @@ def get_tags( title_excluding_html = get_title(context["title"], skip_html_tags=True) # Parse/walk doctree for metadata (tag/description) - description = fields.get("ogp-description", get_description(doctree, desc_len, [title, title_excluding_html])) + description = fields.get( + "ogp-description", + get_description(doctree, desc_len, [title, title_excluding_html]), + ) tags = "\n " @@ -142,6 +147,9 @@ def get_tags( return tags +from sphinx.util import logging + + def html_page_context( app: Sphinx, pagename: str, @@ -149,6 +157,8 @@ def html_page_context( context: Dict[str, Any], doctree: nodes.document, ) -> None: + logger = logging.getLogger(__name__) + logger.info(context.get("meta")) if doctree: context["metatags"] += get_tags(app, context, doctree, app.config) From fd86b2f6ec0847fbd1777fa6a46fc14a82f7b6b4 Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Thu, 27 Jan 2022 15:40:16 +0200 Subject: [PATCH 09/23] Add arbitrary tags support --- sphinxext/opengraph/__init__.py | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/sphinxext/opengraph/__init__.py b/sphinxext/opengraph/__init__.py index cc17601..6bd93a0 100644 --- a/sphinxext/opengraph/__init__.py +++ b/sphinxext/opengraph/__init__.py @@ -34,6 +34,15 @@ def make_tag(property: str, content: str) -> str: return f'\n ' +def make_arbitrary_tags(fields: Dict[str, Any]) -> str: + tags = "" + for name, content in fields.items(): + if name.startswith("og:"): + tags += make_tag(name, content) + + return tags + + def get_tags( app: Sphinx, context: Dict[str, Any], @@ -141,15 +150,15 @@ def get_tags( elif ogp_image_alt is None and title: tags += make_tag("og:image:alt", title) + # arbitrary tags + tags += make_arbitrary_tags(fields) + # custom tags tags += "\n".join(config["ogp_custom_meta_tags"]) return tags -from sphinx.util import logging - - def html_page_context( app: Sphinx, pagename: str, @@ -157,8 +166,6 @@ def html_page_context( context: Dict[str, Any], doctree: nodes.document, ) -> None: - logger = logging.getLogger(__name__) - logger.info(context.get("meta")) if doctree: context["metatags"] += get_tags(app, context, doctree, app.config) From fc6d0230cbccca350a1a4113f44905491db9c578 Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Thu, 27 Jan 2022 15:50:22 +0200 Subject: [PATCH 10/23] Add tests for arbitrary tags --- tests/roots/test-arbitrary-tags/conf.py | 8 ++++++++ tests/roots/test-arbitrary-tags/index.rst | 4 ++++ tests/test_options.py | 6 ++++++ 3 files changed, 18 insertions(+) create mode 100644 tests/roots/test-arbitrary-tags/conf.py create mode 100644 tests/roots/test-arbitrary-tags/index.rst diff --git a/tests/roots/test-arbitrary-tags/conf.py b/tests/roots/test-arbitrary-tags/conf.py new file mode 100644 index 0000000..c2b6c86 --- /dev/null +++ b/tests/roots/test-arbitrary-tags/conf.py @@ -0,0 +1,8 @@ +extensions = ["sphinxext.opengraph"] + +master_doc = "index" +exclude_patterns = ["_build"] + +html_theme = "basic" + +ogp_site_url = "http://example.org/" diff --git a/tests/roots/test-arbitrary-tags/index.rst b/tests/roots/test-arbitrary-tags/index.rst new file mode 100644 index 0000000..07bc4dc --- /dev/null +++ b/tests/roots/test-arbitrary-tags/index.rst @@ -0,0 +1,4 @@ +:og:video: http://example.org/video.mp4 +:og:video:type: video/mp4 + +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. \ No newline at end of file diff --git a/tests/test_options.py b/tests/test_options.py index dfdf0aa..0b588ba 100644 --- a/tests/test_options.py +++ b/tests/test_options.py @@ -180,6 +180,12 @@ def test_overrides_complex(og_meta_tags): assert get_tag_content(og_meta_tags, "image:alt") == "Overridden Alt Text" +@pytest.mark.sphinx("html", testroot="arbitrary-tags") +def test_arbitrary_tags(og_meta_tags): + assert get_tag_content(og_meta_tags, "video") == "http://example.org/video.mp4" + assert get_tag_content(og_meta_tags, "video:type") == "video/mp4" + + # use same as simple, as configuration is identical to overriden @pytest.mark.sphinx("html", testroot="simple") def test_rtd_override(app: Sphinx, monkeypatch): From 13fb48a14ed077c0d8431b80c37a88e2c6319f23 Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Thu, 27 Jan 2022 15:57:31 +0200 Subject: [PATCH 11/23] Add documentation for arbitrary tags --- README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d24977f..94bd506 100644 --- a/README.md +++ b/README.md @@ -88,4 +88,11 @@ Remember that the fields **must** be placed at the very start of the file. You c :ogp-description: New description :ogp-image: http://example.org/image.png :ogp-image-alt: Example Image -``` \ No newline at end of file +``` + +## Arbitrary Tags +Additionally, you can use field lists to add any arbitrary OpenGraph tag not supported by the extension. The syntax for arbitrary tags is `:og:tag: content`. For Example: + +```rst +:og:video: http://example.org/video.mp4 +``` From 0f3e4a8d8f9af0c6ae3a1fb4dfc81b4708271bbb Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Thu, 27 Jan 2022 16:16:12 +0200 Subject: [PATCH 12/23] Prevent creation of multiple tags with the same property --- sphinxext/opengraph/__init__.py | 9 +++++++-- tests/roots/test-arbitrary-tags/index.rst | 1 + tests/test_options.py | 2 ++ 3 files changed, 10 insertions(+), 2 deletions(-) diff --git a/sphinxext/opengraph/__init__.py b/sphinxext/opengraph/__init__.py index 6bd93a0..165e0c8 100644 --- a/sphinxext/opengraph/__init__.py +++ b/sphinxext/opengraph/__init__.py @@ -26,12 +26,16 @@ "heif": "image/heif", "tiff": "image/tiff", } +TAG_LIST = [] 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'\n ' + if property not in TAG_LIST: + TAG_LIST.append(property) + content = content.replace('"', """) + return f'\n ' + return "" def make_arbitrary_tags(fields: Dict[str, Any]) -> str: @@ -49,6 +53,7 @@ def get_tags( doctree: nodes.document, config: Dict[str, Any], ) -> str: + TAG_LIST.clear() # Get field lists for per-poge overrides fields = context["meta"] if fields is None: diff --git a/tests/roots/test-arbitrary-tags/index.rst b/tests/roots/test-arbitrary-tags/index.rst index 07bc4dc..be9b37b 100644 --- a/tests/roots/test-arbitrary-tags/index.rst +++ b/tests/roots/test-arbitrary-tags/index.rst @@ -1,4 +1,5 @@ :og:video: http://example.org/video.mp4 :og:video:type: video/mp4 +:og:url: http://example.com/ 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. \ No newline at end of file diff --git a/tests/test_options.py b/tests/test_options.py index 0b588ba..4225852 100644 --- a/tests/test_options.py +++ b/tests/test_options.py @@ -184,6 +184,8 @@ def test_overrides_complex(og_meta_tags): def test_arbitrary_tags(og_meta_tags): assert get_tag_content(og_meta_tags, "video") == "http://example.org/video.mp4" assert get_tag_content(og_meta_tags, "video:type") == "video/mp4" + assert get_tag_content(og_meta_tags, "url") == "http://example.org/index.html" + assert len([tag for tag in og_meta_tags if tag.get("property") == "og:url"]) == 1 # use same as simple, as configuration is identical to overriden From 0f1298a37781bcff14d70a41ac1c02321c200843 Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Fri, 28 Jan 2022 22:57:30 +0200 Subject: [PATCH 13/23] Revert "Prevent creation of multiple tags with the same property" This reverts commit 0f3e4a8d8f9af0c6ae3a1fb4dfc81b4708271bbb. --- sphinxext/opengraph/__init__.py | 9 ++------- tests/roots/test-arbitrary-tags/index.rst | 1 - tests/test_options.py | 2 -- 3 files changed, 2 insertions(+), 10 deletions(-) diff --git a/sphinxext/opengraph/__init__.py b/sphinxext/opengraph/__init__.py index 165e0c8..6bd93a0 100644 --- a/sphinxext/opengraph/__init__.py +++ b/sphinxext/opengraph/__init__.py @@ -26,16 +26,12 @@ "heif": "image/heif", "tiff": "image/tiff", } -TAG_LIST = [] def make_tag(property: str, content: str) -> str: # Parse quotation, so they won't break html tags if smart quotes are disabled - if property not in TAG_LIST: - TAG_LIST.append(property) - content = content.replace('"', """) - return f'\n ' - return "" + content = content.replace('"', """) + return f'\n ' def make_arbitrary_tags(fields: Dict[str, Any]) -> str: @@ -53,7 +49,6 @@ def get_tags( doctree: nodes.document, config: Dict[str, Any], ) -> str: - TAG_LIST.clear() # Get field lists for per-poge overrides fields = context["meta"] if fields is None: diff --git a/tests/roots/test-arbitrary-tags/index.rst b/tests/roots/test-arbitrary-tags/index.rst index be9b37b..07bc4dc 100644 --- a/tests/roots/test-arbitrary-tags/index.rst +++ b/tests/roots/test-arbitrary-tags/index.rst @@ -1,5 +1,4 @@ :og:video: http://example.org/video.mp4 :og:video:type: video/mp4 -:og:url: http://example.com/ 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. \ No newline at end of file diff --git a/tests/test_options.py b/tests/test_options.py index 4225852..0b588ba 100644 --- a/tests/test_options.py +++ b/tests/test_options.py @@ -184,8 +184,6 @@ def test_overrides_complex(og_meta_tags): def test_arbitrary_tags(og_meta_tags): assert get_tag_content(og_meta_tags, "video") == "http://example.org/video.mp4" assert get_tag_content(og_meta_tags, "video:type") == "video/mp4" - assert get_tag_content(og_meta_tags, "url") == "http://example.org/index.html" - assert len([tag for tag in og_meta_tags if tag.get("property") == "og:url"]) == 1 # use same as simple, as configuration is identical to overriden From b8466034c40ab117c25c4478a6decc6541ee0852 Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Wed, 2 Feb 2022 19:45:52 +0200 Subject: [PATCH 14/23] Rework overrides and arbitrary tags and slightly change syntax --- sphinxext/opengraph/__init__.py | 60 ++++++++------------ tests/roots/test-overrides-complex/index.rst | 7 ++- tests/roots/test-overrides-simple/index.rst | 9 +-- 3 files changed, 34 insertions(+), 42 deletions(-) diff --git a/sphinxext/opengraph/__init__.py b/sphinxext/opengraph/__init__.py index 6bd93a0..9e62159 100644 --- a/sphinxext/opengraph/__init__.py +++ b/sphinxext/opengraph/__init__.py @@ -34,15 +34,6 @@ def make_tag(property: str, content: str) -> str: return f'\n ' -def make_arbitrary_tags(fields: Dict[str, Any]) -> str: - tags = "" - for name, content in fields.items(): - if name.startswith("og:"): - tags += make_tag(name, content) - - return tags - - def get_tags( app: Sphinx, context: Dict[str, Any], @@ -53,11 +44,12 @@ def get_tags( fields = context["meta"] if fields is None: fields = {} + tags = {} # Set length of description try: desc_len = int( - fields.get("ogp-description-length", config["ogp_description_length"]) + fields.get("ogp_description_length", config["ogp_description_length"]) ) except ValueError: desc_len = DEFAULT_DESCRIPTION_LENGTH @@ -67,18 +59,13 @@ def get_tags( title_excluding_html = get_title(context["title"], skip_html_tags=True) # Parse/walk doctree for metadata (tag/description) - description = fields.get( - "ogp-description", - get_description(doctree, desc_len, [title, title_excluding_html]), - ) - - tags = "\n " + description = get_description(doctree, desc_len, [title, title_excluding_html]) # title tag - tags += make_tag("og:title", fields.get("ogp-title", title)) + tags["og:title"] = title # type tag - tags += make_tag("og:type", fields.get("ogp-type", config["ogp_type"])) + tags["og:type"] = config["ogp_type"] if os.getenv("READTHEDOCS") and config["ogp_site_url"] is None: # readthedocs uses html_baseurl for sphinx > 1.8 @@ -104,23 +91,25 @@ def get_tags( page_url = urljoin( config["ogp_site_url"], context["pagename"] + context["file_suffix"] ) - tags += make_tag("og:url", page_url) + tags["og:url"] = page_url # site name tag - site_name = fields.get("ogp-site-name", config["ogp_site_name"]) + site_name = config["ogp_site_name"] if site_name: - tags += make_tag("og:site_name", site_name) + tags["og:site_name"] = site_name # description tag if description: - tags += make_tag("og:description", description) + tags["og:description"] = description # image tag # Get basic values from config - if "ogp-image" in fields: - image_url = fields["ogp-image"] + if "og:image" in fields: + image_url = fields["og:image"] ogp_use_first_image = False - ogp_image_alt = fields.get("ogp-image-alt") + ogp_image_alt = fields.get("og:image:alt") + fields.pop("og:image", None) + fields.pop("og:image:alt", None) else: image_url = config["ogp_image"] ogp_use_first_image = config["ogp_use_first_image"] @@ -140,23 +129,24 @@ def get_tags( if not image_url_parsed.scheme: # Relative image path detected. Make absolute. image_url = urljoin(config["ogp_site_url"], image_url_parsed.path) - tags += make_tag("og:image", image_url) + tags["og:image"] = image_url # Add image alt text (either provided by config or from site_name) if isinstance(ogp_image_alt, str): - tags += make_tag("og:image:alt", ogp_image_alt) + tags["og:image:alt"] = ogp_image_alt elif ogp_image_alt is None and site_name: - tags += make_tag("og:image:alt", site_name) + tags["og:image:alt"] = site_name elif ogp_image_alt is None and title: - tags += make_tag("og:image:alt", title) - - # arbitrary tags - tags += make_arbitrary_tags(fields) + tags["og:image:alt"] = title - # custom tags - tags += "\n".join(config["ogp_custom_meta_tags"]) + # arbitrary tags and overrides + tags.update({k: v for k, v in fields.items() if k.startswith("og:")}) - return tags + return ( + "\n" + + "\n".join([make_tag(p, c) for p, c in tags.items()]) + + "\n".join(config["ogp_custom_meta_tags"]) + ) def html_page_context( diff --git a/tests/roots/test-overrides-complex/index.rst b/tests/roots/test-overrides-complex/index.rst index a105045..6c1f2a6 100644 --- a/tests/roots/test-overrides-complex/index.rst +++ b/tests/roots/test-overrides-complex/index.rst @@ -1,6 +1,7 @@ -:ogp-description-length: 10 -:ogp-image: img/sample.jpg -:ogp-image-alt: Overridden Alt Text +:ogp_description_length: 10 +:og:image: img/sample.jpg +:og: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. diff --git a/tests/roots/test-overrides-simple/index.rst b/tests/roots/test-overrides-simple/index.rst index 478d906..9735a10 100644 --- a/tests/roots/test-overrides-simple/index.rst +++ b/tests/roots/test-overrides-simple/index.rst @@ -1,7 +1,8 @@ -:ogp-description: Overridden description -:ogp-title: Overridden Title -:ogp-type: article -:ogp-image: http://example.org/overridden-image.png +:og:description: Overridden description +:og:title: Overridden Title +:og:type: article +:og: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. From 4ad988fca01b1edbf854413293fb6786bf4b15ee Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Wed, 2 Feb 2022 19:58:32 +0200 Subject: [PATCH 15/23] Update readme.md and adjust image:alt functionality --- README.md | 29 +++++++++++++++-------------- sphinxext/opengraph/__init__.py | 4 ++-- 2 files changed, 17 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 94bd506..b4f8b28 100644 --- a/README.md +++ b/README.md @@ -62,36 +62,37 @@ 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. +[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 and set unsupported arbitrary OpenGraph tags. 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 +These are some overrides that can be used, you can actually override any tag and field lists will always take priority. -* `: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:` +* `:og_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`. Note the slightly different syntax because this isn't directly an OpenGraph tag. +* `:og:description:` * Lets you override the description of the page. -* `:ogp-title:` +* `:og:title:` * Lets you override the title of the page. -* `:ogp-type:` +* `:og:type:` * Override the type of the page, for the list of available types take a look at https://ogp.me/#types. -* `:ogp-image:` +* `: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. +* `:ogp:image:alt:` + * Sets the alt text. Will be ignored if there is no image set. ### 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 +:og:description: New description +:og:image: http://example.org/image.png +:og:image:alt: Example Image ``` -## Arbitrary Tags -Additionally, you can use field lists to add any arbitrary OpenGraph tag not supported by the extension. The syntax for arbitrary tags is `:og:tag: content`. For Example: +### Arbitrary Tags +Additionally, you can use field lists to add any arbitrary OpenGraph tag not supported by the extension. The syntax for arbitrary tags is the same with `:og:tag: content`. For Example: ```rst :og:video: http://example.org/video.mp4 diff --git a/sphinxext/opengraph/__init__.py b/sphinxext/opengraph/__init__.py index 9e62159..69ee881 100644 --- a/sphinxext/opengraph/__init__.py +++ b/sphinxext/opengraph/__init__.py @@ -109,11 +109,11 @@ def get_tags( ogp_use_first_image = False ogp_image_alt = fields.get("og:image:alt") fields.pop("og:image", None) - fields.pop("og:image:alt", None) else: image_url = config["ogp_image"] ogp_use_first_image = config["ogp_use_first_image"] - ogp_image_alt = config["ogp_image_alt"] + ogp_image_alt = fields.get("og:image:alt", config["ogp_image_alt"]) + fields.pop("og:image:alt", None) if ogp_use_first_image: first_image = doctree.next_node(nodes.image) From d0707a9b81a9093ee9e6f99f3e5f46e25719579f Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Wed, 2 Feb 2022 20:21:41 +0200 Subject: [PATCH 16/23] Apply suggestions from code review Co-authored-by: Vasista Vovveti --- README.md | 8 ++++++-- sphinxext/opengraph/__init__.py | 3 +-- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index b4f8b28..5ccbc49 100644 --- a/README.md +++ b/README.md @@ -89,11 +89,15 @@ Remember that the fields **must** be placed at the very start of the file. You c :og:description: New description :og:image: http://example.org/image.png :og:image:alt: Example Image -``` + +Page contents +============= ### Arbitrary Tags Additionally, you can use field lists to add any arbitrary OpenGraph tag not supported by the extension. The syntax for arbitrary tags is the same with `:og:tag: content`. For Example: ```rst :og:video: http://example.org/video.mp4 -``` + +Page contents +============= diff --git a/sphinxext/opengraph/__init__.py b/sphinxext/opengraph/__init__.py index 69ee881..ceee6d2 100644 --- a/sphinxext/opengraph/__init__.py +++ b/sphinxext/opengraph/__init__.py @@ -144,8 +144,7 @@ def get_tags( return ( "\n" - + "\n".join([make_tag(p, c) for p, c in tags.items()]) - + "\n".join(config["ogp_custom_meta_tags"]) + + "\n".join([make_tag(p, c) for p, c in tags.items()] + config["ogp_custom_meta_tags"]) ) From c3ab42428bce51a7ab518f1bed5a0408daeae527 Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Wed, 2 Feb 2022 20:23:52 +0200 Subject: [PATCH 17/23] Run black --- sphinxext/opengraph/__init__.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/sphinxext/opengraph/__init__.py b/sphinxext/opengraph/__init__.py index ceee6d2..2bfd8e6 100644 --- a/sphinxext/opengraph/__init__.py +++ b/sphinxext/opengraph/__init__.py @@ -142,9 +142,8 @@ def get_tags( # arbitrary tags and overrides tags.update({k: v for k, v in fields.items() if k.startswith("og:")}) - return ( - "\n" - + "\n".join([make_tag(p, c) for p, c in tags.items()] + config["ogp_custom_meta_tags"]) + return "\n" + "\n".join( + [make_tag(p, c) for p, c in tags.items()] + config["ogp_custom_meta_tags"] ) From 8ee2ff681850067211d84c48a627e29eb735311c Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Wed, 2 Feb 2022 23:30:44 +0200 Subject: [PATCH 18/23] Remove any support for relative paths with field lists and add a note --- README.md | 8 ++++++-- sphinxext/opengraph/__init__.py | 11 +++++++---- 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 5ccbc49..88cce43 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Users hosting documentation on Read The Docs *do not* need to set any of the fol * `ogp_site_name` * This is not required. Name of the site. This is displayed above the title. * `ogp_image` - * This is not required. Link to image to show. + * This is not required. Link to image to show. Note that all relative paths are converted to be relative to the root of the html output. * `ogp_image_alt` * This is not required. Alt text for image. Defaults to using `ogp_site_name` or the document's title as alt text, if available. Set to `False` if you want to turn off alt text completely. * `ogp_use_first_image` @@ -78,7 +78,7 @@ These are some overrides that can be used, you can actually override any tag and * `:og: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. + * Set the image for the page. Note: Relative file paths are ***not*** currently supported when using field lists. * `:ogp:image:alt:` * Sets the alt text. Will be ignored if there is no image set. @@ -92,12 +92,16 @@ Remember that the fields **must** be placed at the very start of the file. You c Page contents ============= +``` ### Arbitrary Tags Additionally, you can use field lists to add any arbitrary OpenGraph tag not supported by the extension. The syntax for arbitrary tags is the same with `:og:tag: content`. For Example: +Note: Relative file paths are ***not*** currently supported for images, videos and audio when using field lists. + ```rst :og:video: http://example.org/video.mp4 Page contents ============= +``` diff --git a/sphinxext/opengraph/__init__.py b/sphinxext/opengraph/__init__.py index 2bfd8e6..9724ae3 100644 --- a/sphinxext/opengraph/__init__.py +++ b/sphinxext/opengraph/__init__.py @@ -113,6 +113,13 @@ def get_tags( image_url = config["ogp_image"] ogp_use_first_image = config["ogp_use_first_image"] ogp_image_alt = fields.get("og:image:alt", config["ogp_image_alt"]) + + if image_url: + image_url_parsed = urlparse(image_url) + if not image_url_parsed.scheme: + # Relative image path detected. Make absolute. + image_url = urljoin(config["ogp_site_url"], image_url_parsed.path) + fields.pop("og:image:alt", None) if ogp_use_first_image: @@ -125,10 +132,6 @@ def get_tags( ogp_image_alt = first_image.get("alt", None) if image_url: - image_url_parsed = urlparse(image_url) - if not image_url_parsed.scheme: - # Relative image path detected. Make absolute. - image_url = urljoin(config["ogp_site_url"], image_url_parsed.path) tags["og:image"] = image_url # Add image alt text (either provided by config or from site_name) From 6db225b0e8820b836b8fb89ffed3bead2439a367 Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Thu, 3 Feb 2022 02:52:37 +0200 Subject: [PATCH 19/23] Revert relative url behaviour --- sphinxext/opengraph/__init__.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/sphinxext/opengraph/__init__.py b/sphinxext/opengraph/__init__.py index 9724ae3..3e69994 100644 --- a/sphinxext/opengraph/__init__.py +++ b/sphinxext/opengraph/__init__.py @@ -114,12 +114,6 @@ def get_tags( ogp_use_first_image = config["ogp_use_first_image"] ogp_image_alt = fields.get("og:image:alt", config["ogp_image_alt"]) - if image_url: - image_url_parsed = urlparse(image_url) - if not image_url_parsed.scheme: - # Relative image path detected. Make absolute. - image_url = urljoin(config["ogp_site_url"], image_url_parsed.path) - fields.pop("og:image:alt", None) if ogp_use_first_image: @@ -132,6 +126,11 @@ def get_tags( ogp_image_alt = first_image.get("alt", None) if image_url: + if image_url: + image_url_parsed = urlparse(image_url) + if not image_url_parsed.scheme: + # Relative image path detected. Make absolute. + image_url = urljoin(config["ogp_site_url"], image_url_parsed.path) tags["og:image"] = image_url # Add image alt text (either provided by config or from site_name) From 7ec4e17bc666f698807952dbc20d0be632791553 Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Thu, 3 Feb 2022 03:04:00 +0200 Subject: [PATCH 20/23] Change readme to align with previous commit --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 88cce43..1045004 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ These are some overrides that can be used, you can actually override any tag and * `:og: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. Note: Relative file paths are ***not*** currently supported when using field lists. + * Set the image for the page.[^1] * `:ogp:image:alt:` * Sets the alt text. Will be ignored if there is no image set. @@ -97,11 +97,11 @@ Page contents ### Arbitrary Tags Additionally, you can use field lists to add any arbitrary OpenGraph tag not supported by the extension. The syntax for arbitrary tags is the same with `:og:tag: content`. For Example: -Note: Relative file paths are ***not*** currently supported for images, videos and audio when using field lists. - ```rst :og:video: http://example.org/video.mp4 Page contents ============= ``` + +[^1]: Note: Relative file paths for images are currently converted to be relative to the root of the website as defined by `ogp_site_name` ***not*** the source reStructuredText file. Additionally, relative file paths for videos and audio are currently **not** supported please use an absolute path instead. From a43d75be0b1e72f75991e1b839b3d9cd9102d7d7 Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Thu, 3 Feb 2022 22:20:17 +0200 Subject: [PATCH 21/23] Disable relative file paths with field lists --- README.md | 4 ++-- sphinxext/opengraph/__init__.py | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1045004..aac44db 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,7 @@ Page contents ============= ``` -### Arbitrary Tags +### Arbitrary Tags[^1] Additionally, you can use field lists to add any arbitrary OpenGraph tag not supported by the extension. The syntax for arbitrary tags is the same with `:og:tag: content`. For Example: ```rst @@ -104,4 +104,4 @@ Page contents ============= ``` -[^1]: Note: Relative file paths for images are currently converted to be relative to the root of the website as defined by `ogp_site_name` ***not*** the source reStructuredText file. Additionally, relative file paths for videos and audio are currently **not** supported please use an absolute path instead. +[^1]: Note: Relative file paths for images, videos and audio are currently **not** supported when using field lists. Please use an absolute path instead. diff --git a/sphinxext/opengraph/__init__.py b/sphinxext/opengraph/__init__.py index 3e69994..ab1e6a3 100644 --- a/sphinxext/opengraph/__init__.py +++ b/sphinxext/opengraph/__init__.py @@ -126,7 +126,8 @@ def get_tags( ogp_image_alt = first_image.get("alt", None) if image_url: - if image_url: + # temporarily disable relative image paths with field lists + if image_url and "og:image" not in fields: image_url_parsed = urlparse(image_url) if not image_url_parsed.scheme: # Relative image path detected. Make absolute. From 18c4aa6ff833921c64f93e4e1660571b7ecb595e Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Thu, 3 Feb 2022 22:50:31 +0200 Subject: [PATCH 22/23] Fix typo in comments Co-authored-by: Dalton Smith --- sphinxext/opengraph/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinxext/opengraph/__init__.py b/sphinxext/opengraph/__init__.py index ab1e6a3..e139bac 100644 --- a/sphinxext/opengraph/__init__.py +++ b/sphinxext/opengraph/__init__.py @@ -40,7 +40,7 @@ def get_tags( doctree: nodes.document, config: Dict[str, Any], ) -> str: - # Get field lists for per-poge overrides + # Get field lists for per-page overrides fields = context["meta"] if fields is None: fields = {} From 1ca449dc826e4b56eff1c7a00dcb2142856e367e Mon Sep 17 00:00:00 2001 From: Itay Ziv Date: Thu, 3 Feb 2022 23:36:06 +0200 Subject: [PATCH 23/23] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index aac44db..6adbc34 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Users hosting documentation on Read The Docs *do not* need to set any of the fol * `ogp_site_name` * This is not required. Name of the site. This is displayed above the title. * `ogp_image` - * This is not required. Link to image to show. Note that all relative paths are converted to be relative to the root of the html output. + * This is not required. Link to image to show. Note that all relative paths are converted to be relative to the root of the html output as defined by `ogp_site_name. * `ogp_image_alt` * This is not required. Alt text for image. Defaults to using `ogp_site_name` or the document's title as alt text, if available. Set to `False` if you want to turn off alt text completely. * `ogp_use_first_image`