Directives¶

This extension comes with directives that can be used to generate an image for a social card within a document’s source file. The primary directive is the social-card directive. The image-generator directive is a derivative to inject generated images into the document.

.. social-card::¶

This directive generates an image to use for a social card.

Argument:¶

The optional argument (written in JSON syntax) can be used to override the configuration options set with social_cards. If no argument is provided, then the value from social_cards is used by default. Both the social_cards value and the argument provided are merged into a localized configuration.

An example of passing the layout as an argument:

.. social-card::
    {
        "cards_layout": "default/variant",
        "cards_layout_options": {
            "background_color": "orange"
        }
    }
    :dry-run:

conf.py¶

social_cards = {
    "description": "Generate social media cards for documentation pages with Sphinx",
    "site_url": "https://sphinx-social-cards.readthedocs.io/en/latest/",
    "cards_layout": "default/variant",
    "cards_layout_options": {
        "background_color": "orange"
    }
}

Content:¶

The content block (if provided) serves as a custom layout written in YAML syntax. If no content block is provided, then the cards_layout value is used.

An example of passing the layout as a content block:

.. social-card::
    :dry-run:

    size: { width: 400, height: 200 }
    layers:
      - ellipse:
          color: green
          border: { width: 15, color: blue }
      - typography: { content: SSC, align: center, color: red }
        size: { width: 350, height: 150 }
        offset: { x: 25, y: 25 }

my-layout.yml¶

size: { width: 400, height: 200 }
layers:
  - ellipse:
      color: green
      border: { width: 15, color: blue }
  - typography: { content: SSC, align: center, color: red }
    size: { width: 350, height: 150 }
    offset: { x: 25, y: 25 }

Useless Options (demonstration purposes only)

All options listed below are not meant for production use. They are intended for generating example images and injecting them into the document (without altering the page’s metadata or the social_cards configuration).

If you plan to use this directive to inject images into the document, then consider using the image-generator directive instead. However, metadata and configuration cannot be manipulated using the image-generator directive.

:meta-data: (JSON)¶

An optional string of Metadata written in JSON syntax.

Don’t forget to indent a multi-lined value:¶

.. social-card::
    :dry-run:
    :meta-data:
        {
            "title": "My overridden page title",
            "icon": "images/messages.png"
        }
    :hide-meta-data:

:dry-run: (flag)¶

This flag (if specified) will prevent the generated image from being used as the resulting document’s social card. No metadata will be injected in the rendered document if this option is specified.

:hide-meta-data: (flag)¶

This flag (if specified) will hide the generated literal block displaying the given :meta-data:. If no :meta-data: is provided or the :dry-run: option is not used, then this flag is automatically asserted.

:hide-conf: (flag)¶

This flag (if specified) will hide the generated literal block displaying the configuration (given as an argument). If no configuration (directive argument) is provided or the :dry-run: option is not used, then this flag is automatically asserted.

:hide-layout: (flag)¶

This flag (if specified) will hide the generated literal block displaying the given layout (given as a content block). If no layout (directive content) is provided or the :dry-run: option is not used, then this flag is automatically asserted.

:meta-data-caption: (text)¶

This option will change the caption for the generated literal block displaying the given :meta-data:. Defaults to my-document.rst (meta-data).

:conf-caption: (text)¶

This option will change the caption for the generated literal block displaying the configuration (given as an argument). Defaults to conf.py.

:layout-caption: (text)¶

This option will change the caption for the generated literal block displaying the given layout (given as a content block). Defaults to my-layout.yml.

.. image-generator::¶

A simple directive designed to mimic the rST image directive, but the image is generated using this extension’s mechanisms. If no content or argument is given, then the cards_layout value is used.

Important

Compared to the social-card directive, this directive creates images that are not meant to be used as social media cards. Rather, it just creates an image and adds it to the document.

Seealso

Review the options to the rST image directive as the options are all the same. If no :target: option was given, then the image’s URI is used as a target.

Argument:¶

The only optional argument that this directive accepts is the layout name as given to the cards_layout.

An example of passing the layout as an argument:

.. image-generator:: default/variant
    :align: center

Content:¶

The content block (if provided) serves as a custom layout written in YAML syntax.

An example of passing the layout as a content block:

.. image-generator::
    :align: center

    size: { width: 400, height: 200 }
    layers:
      - rectangle:
          radius: 50
          color: green
          border: { width: 15, color: blue }
      - typography: { content: SSC, align: center, color: red }
        size: { width: 350, height: 150 }
        offset: { x: 25, y: 25 }