# sphinxext-opengraph
[](https://github.com/wpilibsuite/sphinxext-opengraph/actions)
[](https://github.com/psf/black)
Sphinx extension to generate [Open Graph metadata](https://ogp.me/) for each page of your documentation.
## Installation
```sh
python -m pip install sphinxext-opengraph
```
## Usage
Just add `sphinxext.opengraph` to your extensions list in your `conf.py`
```python
extensions = [
"sphinxext.opengraph",
]
```
## Options
These values are placed in the `conf.py` of your Sphinx project.
Users hosting documentation on Read The Docs *do not* need to set any of the following unless custom configuration is wanted. The extension will automatically retrieve your site URL.
* `ogp_site_url`
* This config option is very important, set it to the URL the site is being hosted on.
* `ogp_description_length`
* Configure the amount of characters taken from a page. The default of 200 is probably good for most people. If something other than a number is used, it defaults back to 200.
* `ogp_site_name`
* This is not required. Name of the site. This is displayed above the title. Defaults to the Sphinx [`project`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-project) config value. Set to `False` to unset and use no default.
* `ogp_social_cards`
* Configuration for automatically creating social media card PNGs for each page.
For more information, see [the social media cards docs](docs/source/socialcards.md).
* `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 as defined by `ogp_site_url`.
* `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`
* This is not required. Set to `True` to use each page's first image, if available. If set to `True` but no image is found, Sphinx will use `ogp_image` instead.
* `ogp_type`
* This sets the ogp type attribute, for more information on the types available please take a look at [https://ogp.me/#types](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.
* `ogp_enable_meta_description`
* This is not required. When `True`, generates `<meta name="description" content="...">` from the page.
## Example Config
### Simple Config
```python
ogp_site_url = "http://example.org/"
ogp_image = "http://example.org/image.png"
```
### Advanced Config
```python
ogp_site_url = "http://example.org/"
ogp_image = "http://example.org/image.png"
ogp_description_length = 300
ogp_type = "article"
ogp_custom_meta_tags = [
'<meta property="og:ignore_canonical" content="true" />',
]
ogp_enable_meta_description = True
```
## 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 and set unsupported arbitrary Open Graph 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 on individual pages, 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`.[^1]
* `:ogp_disable:`
* Disables generation of Open Graph tags on the page.[^1]
* `:og:description:`
* Lets you override the description of the page.
* `:description:` or `.. meta::\n :description:`
* Sets the `<meta name="description" content="...">` description.
* `:og:title:`
* Lets you override the title of the page.
* `:og:type:`
* Override the type of the page, for the list of available types take a look at https://ogp.me/#types.
* `:og:image:`
* Set the image for the page.[^2]
* `:og: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
:og:description: New description
:og:image: http://example.org/image.png
:og:image:alt: Example Image
Page contents
=============
```
### Arbitrary Tags[^2]
Additionally, you can use field lists to add any arbitrary Open Graph 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
=============
```
[^1]: Note the slightly different syntax because this isn't directly an Open Graph tag.
[^2]: Note: Relative file paths for images, videos and audio are currently **not** supported when using field lists. Please use an absolute path instead.
Raw data
{
"_id": null,
"home_page": "https://github.com/wpilibsuite/sphinxext-opengraph",
"name": "sphinxext-opengraph",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Itay Ziv",
"author_email": "itay220204@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1c/5b/4302fe33c88dbfb572e2c1cad26735164c23f16fb8dba94ddb1867d0ef06/sphinxext-opengraph-0.9.1.tar.gz",
"platform": null,
"description": "# sphinxext-opengraph\n\n[](https://github.com/wpilibsuite/sphinxext-opengraph/actions)\n[](https://github.com/psf/black)\n\nSphinx extension to generate [Open Graph metadata](https://ogp.me/) for each page of your documentation.\n\n## Installation\n\n```sh\npython -m pip install sphinxext-opengraph\n```\n\n## Usage\nJust add `sphinxext.opengraph` to your extensions list in your `conf.py`\n\n```python\nextensions = [\n \"sphinxext.opengraph\",\n]\n```\n## Options\nThese values are placed in the `conf.py` of your Sphinx project.\n\nUsers hosting documentation on Read The Docs *do not* need to set any of the following unless custom configuration is wanted. The extension will automatically retrieve your site URL.\n\n* `ogp_site_url`\n * This config option is very important, set it to the URL the site is being hosted on. \n* `ogp_description_length`\n * Configure the amount of characters taken from a page. The default of 200 is probably good for most people. If something other than a number is used, it defaults back to 200. \n* `ogp_site_name`\n * This is not required. Name of the site. This is displayed above the title. Defaults to the Sphinx [`project`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-project) config value. Set to `False` to unset and use no default.\n* `ogp_social_cards`\n * Configuration for automatically creating social media card PNGs for each page.\n For more information, see [the social media cards docs](docs/source/socialcards.md).\n* `ogp_image`\n * 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_url`.\n* `ogp_image_alt`\n * 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.\n* `ogp_use_first_image`\n * This is not required. Set to `True` to use each page's first image, if available. If set to `True` but no image is found, Sphinx will use `ogp_image` instead.\n* `ogp_type`\n * This sets the ogp type attribute, for more information on the types available please take a look at [https://ogp.me/#types](https://ogp.me/#types). By default it is set to `website`, which should be fine for most use cases.\n* `ogp_custom_meta_tags`\n * This is not required. List of custom html snippets to insert.\n* `ogp_enable_meta_description`\n * This is not required. When `True`, generates `<meta name=\"description\" content=\"...\">` from the page.\n\n## Example Config\n\n### Simple Config\n\n```python\nogp_site_url = \"http://example.org/\"\nogp_image = \"http://example.org/image.png\"\n```\n\n### Advanced Config\n\n```python\nogp_site_url = \"http://example.org/\"\nogp_image = \"http://example.org/image.png\"\nogp_description_length = 300\nogp_type = \"article\"\n\nogp_custom_meta_tags = [\n '<meta property=\"og:ignore_canonical\" content=\"true\" />',\n]\n\nogp_enable_meta_description = True\n```\n\n## Per Page Overrides\n[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 Open Graph tags.\n\nMake 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.\n\n### Overrides\nThese are some overrides that can be used on individual pages, you can actually override any tag and field lists will always take priority.\n\n* `:ogp_description_length:`\n * 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`.[^1]\n* `:ogp_disable:`\n * Disables generation of Open Graph tags on the page.[^1]\n* `:og:description:`\n * Lets you override the description of the page.\n* `:description:` or `.. meta::\\n :description:`\n * Sets the `<meta name=\"description\" content=\"...\">` description.\n* `:og:title:`\n * Lets you override the title of the page.\n* `:og:type:`\n * Override the type of the page, for the list of available types take a look at https://ogp.me/#types.\n* `:og:image:`\n * Set the image for the page.[^2]\n* `:og:image:alt:`\n * Sets the alt text. Will be ignored if there is no image set.\n\n### Example\nRemember 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.\n\n```rst\n:og:description: New description\n:og:image: http://example.org/image.png\n:og:image:alt: Example Image\n\nPage contents\n=============\n```\n\n### Arbitrary Tags[^2]\nAdditionally, you can use field lists to add any arbitrary Open Graph tag not supported by the extension. The syntax for arbitrary tags is the same with `:og:tag: content`. For example:\n\n```rst\n:og:video: http://example.org/video.mp4\n\nPage contents\n=============\n```\n\n[^1]: Note the slightly different syntax because this isn't directly an Open Graph tag.\n[^2]: Note: Relative file paths for images, videos and audio are currently **not** supported when using field lists. Please use an absolute path instead.\n",
"bugtrack_url": null,
"license": "LICENSE.md",
"summary": "Sphinx Extension to enable OGP support",
"version": "0.9.1",
"project_urls": {
"Homepage": "https://github.com/wpilibsuite/sphinxext-opengraph"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "920a970b80b4fa1feeb6deb6f2e22d4cb14e388b27b315a1afdb9db930ff91a4",
"md5": "81b8ef2dab1e89702495b997901d0f0d",
"sha256": "b3b230cc6a5b5189139df937f0d9c7b23c7c204493b22646273687969dcb760e"
},
"downloads": -1,
"filename": "sphinxext_opengraph-0.9.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "81b8ef2dab1e89702495b997901d0f0d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 1005241,
"upload_time": "2023-12-14T12:11:21",
"upload_time_iso_8601": "2023-12-14T12:11:21.608287Z",
"url": "https://files.pythonhosted.org/packages/92/0a/970b80b4fa1feeb6deb6f2e22d4cb14e388b27b315a1afdb9db930ff91a4/sphinxext_opengraph-0.9.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1c5b4302fe33c88dbfb572e2c1cad26735164c23f16fb8dba94ddb1867d0ef06",
"md5": "c67696654492bdca614f151b77c224d3",
"sha256": "dd2868a1e7c9497977fbbf44cc0844a42af39ca65fe1bb0272518af225d06fc5"
},
"downloads": -1,
"filename": "sphinxext-opengraph-0.9.1.tar.gz",
"has_sig": false,
"md5_digest": "c67696654492bdca614f151b77c224d3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 1034511,
"upload_time": "2023-12-14T12:11:24",
"upload_time_iso_8601": "2023-12-14T12:11:24.613074Z",
"url": "https://files.pythonhosted.org/packages/1c/5b/4302fe33c88dbfb572e2c1cad26735164c23f16fb8dba94ddb1867d0ef06/sphinxext-opengraph-0.9.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-14 12:11:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wpilibsuite",
"github_project": "sphinxext-opengraph",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinxext-opengraph"
}
JSON
