

Emoji

概观

The Emoji extension adds support for inserting emoji via simple short names enclosed within colons: :short_name:. This is accomplished by using a short name index to map easy to remember names to associated Unicode data. The Unicode data is then converted into actual Unicode emoji characters and/or special HTML elements (usually images) that represent the emoji.

Emoji Example

:smile: :heart: :thumbsup:

支持的Emoji提供者

There are a number of emoji short name conventions that people may be aware of. These conventions are always tied to a specific emoji set. These conventions differ because there is no official Unicode short name convention. At the present, Emoji chooses to focus on three specific emoji sets:

• Gemoji ( ): Gemoji is GitHub's open source emoji solution. It contains a lot of common emoji and a couple special, non Unicode emoji (like Gemoji's :octocat:). If you are a GitHub user, you are probably familiar with some of the short names associated with it. Their associated CDN contains the emoji in 75x75 PNG format.
• EmojiOne ( ): EmojiOne is a very complete, high quality emoji set with support for gender and skin tone modifiers. Their free emoji set includes PNGs in sizes of 32x32, 64x64, and 128x128 which are all available via a CDN. Their older (version 2.2.7) emoji set, which contains less emoji, offers SVG images as well. Emoji supports EmojiOne's newest short name mapping, but it can be used for their older set, but short names for emoji that have been added since the old set will not map to any images if this is done.
• Twemoji ( ): Twemoji is Twitter's open source emoji set which also covers a great many emoji with skin tones and gender modifiers. The hosted CDN provides 72x72 PNG emoji or SVG emoji. While Gemoji and EmojiOne have a short name convention, Twemoji does not, and there are currently no 3^rd projects that provide short names anywhere close to all the provided emoji. Since EmojiOne has the largest emoji library of the supported sets, we use EmojiOne's short name list for Twemoji. There will be a reasonable attempt to patch in emoji not found in EmojiOne's index, but if EmojiOne is ever significantly behind, we may wait for EmojiOne to catch up.

Emoji Image Licensing

PyMdown Extensions has no affiliation with EmojiOne, Gemoji, or Twemoji. The indexes generated from their sources are covered under their respective licensing. When using their images or CSS, please see their licensing terms to ensure proper usage and attributions.

EmojiOne: https://www.emojione.com/developers/free-license
Gemoji: https://github.com/github/gemoji/blob/master/LICENSE
Twemoji: https://github.com/twitter/twemoji/blob/gh-pages/LICENSE-GRAPHICS

All short name indexes that Emoji uses are generated from EmojiOne's or Gemoji's latest official source tag – Twemoji uses EmojiOne's index as the Twemoji repository does not ship with a short name index. The indexes contain the emoji names, short names, values, etc.; everything needed to insert Unicode emoji characters or specially crafted HTML elements.

Emoji 输出格式

Depending on your needs, you may have different requirements for how emoji get displayed in your documents. You may want to use PNG images, or maybe you really like SVG images. Maybe you just want to convert short names to the actual Unicode code points. There are a variety of ways you may want to output emoji, and the Emoji extension has you covered.

Emoji provides various output formats that take the Unicode data associated with a short name (or the short name itself in the case of a custom emoji) and generates an HTML output. Not all of the provided output formats will work for each emoji index, but there are a few that should work for all three. Check out Default Emoji Generators or Custom Emoji Generators to learn more.

默认 Emoji 索引

By default, Emoji provides three indexes: emojione, gemoji, and twemoji. All indexes are generated from the most recent official release tag source (in the case of Twemoji, sort names are acquired from EmojiOne's generated index). They can be used by passing in one of the three functions below via the emoji_index parameter. Pass the actual function reference, not a string. If you need to create your own, just check out Custom Emoji Indexes.

pymdownx.emoji.emojione : This is the default function that is used, and it provides an index using the latest EmojiOne supported emoji (at the time of release).

You can always find out what tag it was built with by doing the following:

```pycon3
>>> import pymdownx.emoji1_db as e1db
>>> e1db.version
'v3.1.2'
```

!!! warning "EmojiOne Update"
    Recent EmojiOne 3.0 release dropped fee SVG support. PNG support can still be obtained via CDNs.

    While EmojiOne only offers 3.0 vector graphics to paying customers now, you can still get SVG support. By default, we still use 2.2.7 SVGs, but you won't get images for emoji added after 2.2.7. If using SVG sprites, you will have to [download][emojione-sprites-svg] the sprite SVG.

pymdownx.emoji.gemoji : This function provides an index of the latest Gemoji supported emoji (at the time of release).

You can always find out what tag it was built with by doing the following:

```pycon3
>>> import pymdownx.gemoji_db as gmdb
>>> gmdb.version
'v3.0.0'
```

pymdownx.emoji.twemoji : This function provides an index of the latest Twemoji supported emoji (at the time of release). The associated short names are currently borrowed from EmojiOne's index. These few emoji are currently Twemoji specific, two of which are likely to always be as they are not part of the official emoji spec:

- `:skier_tone1:`
- `:skier_tone2:`
- `:skier_tone3:`
- `:skier_tone4:`
- `:skier_tone5:`
- `:pirage_flag:`
- `:shibuya:`

You can always find out what tag it was built with by doing the following:

```pycon3
>>> import pymdownx.twemoji_db as twdb
>>> twdb.version
'v2.5.0'
```

默认 Emoji Generators

Emoji provides six default emoji generators. PNG output and Unicode code point output are supported for all three indexes. SVG output is only supported for Twemoji and the older 2.2.7 EmojiOne set. PNG sprites and the "Font Awesome" like format are only supported by EmojiOne. SVG sprites is only supported by the 2.2.7 EmojiOne.

You can select a generator to use by passing in one of the functions below via the emoji_generator parameter. Pass the actual function reference, not a string. If you need to create your own, just check out Custom Emoji Generators.

pymdownx.emoji.to_png : This is a general purpose generator which provides EmojiOne, GitHub, and Twemoji CDN path(s) out of the box. Depending on the index you've chosen, you the appropriate CDN will be provided. If this ever gets out of date, a new CDN can be passed in via image_path and/or non_standard_image_path. EmojiOne actually has multiple PNGs sizes of 32, 64, and 128, but the default CDN path is the one for size 64: https://cdn.jsdelivr.net/emojione/assets/3.1/png/64/. You can change it for a larger or smaller PNG size by updating the size in the URL and passing the new URL in through image_path. The PNG output form is as follows:

```html
<img alt="😄" class="emojione" src="https://cdn.jsdelivr.net/emojione/assets/3.1/png/64/1f604.png" title=":smile:" />
```

**Generator Specific Options**

Option                    | Type       | Default                        | Description
------------------------- | ---------- | ------------------------------ | -----------
`classes`                 | string     | Name of the index used         | Specifies the class(es) to be used in the image element.
`image_path`              | string     | CDN for the default index used | This can be either a local path or a CDN containing the assets.  By default, an appropriate CDN is provided for EmojiOne, Gemoji, and Twemoji depending on which index is being used.
`non_standard_image_path` | string     | CDN for the default index used | This can be either a local path, or a CDN containing the assets. Currently, only Gemoji's non-standard emoji take advantage of this as the GitHub CDN alters the path slightly for its non-Unicode emoji.  By default, an appropriate CDN is provided for Gemoji.
`attributes`              | dictionary | `#!py3 {}`                      | A dictionary containing tag attributes as key value string pairs. The dictionary keys are the attribute names and dictionary values are the attribute values.

pymdownx.emoji.to_svg : This generator was written to output SVG images and supports EmojiOne and Twemoji. EmojiOne's SVG support is only for the free 2.2.7 release, so the default CDN still references the 2.2.7 release. EmojiOne short names added after 2.2.7 will not find images. You can of course reference local SVG images as well by pointing image_path to them as well. The SVG image outputs as:

```html
<img alt="😄" class="emojione" src="https://cdn.jsdelivr.net/emojione/assets/svg/1f604.svg" title=":smile:" />
```

**Generator Specific Options**

Option       | Type       | Default                   | Description
------------ | ---------- | ------------------------- | -----------
`classes`    | string     | Name of the index used    | Specifies the class(es) to be used in the image element. The default will match the name of the index used.
`image_path` | string     | A CDN for EmojiOne images | This can be either a local path or a CDN containing the assets.  By default, an appropriate CDN is provided for EmojiOne.
`attributes` | dictionary | `#!py3 {}`                 | A dictionary containing tag attributes as key value string pairs. The dictionary keys are the attribute names and dictionary values are the attribute values.

pymdownx.emoji.to_png_sprite : This generator was written to support PNG sprite output for EmojiOne. It is expected that this will be used in conjunction with the the official EmojiOne CSS. You can include the CSS from the CDN in your document. The CSS comes in three sizes: 32, 64, 128. Make sure to set the correct size in the options to generate the appropriate classes.

Example CDN for the 3.1 version with 64px PNGs: `https://cdn.jsdelivr.net/emojione/assets/3.1/sprites/emojione-sprite-64.min.css`.

`to_png_sprite` outputs the emoji as a span in the form below.  The CSS will apply the appropriate mapping in the sprite PNG to the background image of the span.

```html
<span class="emojione-64-people _1f604" title=":smile:">😄</span>
```

**Generator Specific Options**

Option       | Type       | Default                | Description
------------ | ---------- | ---------------------- | -----------
`classes`    | string     | Name of the index used | Class(es) used for the span where the classes are inserted as "class" in the following template: `#!py3 '%(class)s-%(size)s-%(category)s _%(unicode)s'`.
`size`       | int        | `#!py3 64`              | Integer specifying the size for the class above.
`attributes` | dictionary | `#!py3 {}`              | A dictionary containing tag attributes as key value string pairs. The dictionary keys are the attribute names and dictionary values are the attribute values.

pymdownx.emoji.to_svg_sprite : This was written to support EmojiOne SVG sprite output. The output form was taken directly from an example in the EmojiOne source. It is expected that the the user will provide a local version of the official SVG sprite and the path to it. Unfortunately there is no free 3.0 SVG sprite, so you will need to download the old 2.27 one. The output is:

```html
<svg class="emojione"><description>😄</description><use xlink:href="./../assets/sprites/emojione.sprites.svg#emoji-1f604"></use></svg>
```

**Generator Specific Options**

Option       | Type   | Default                | Description
------------ | ------ | ---------------------- | -----------
`classes`    | string | Name of the index used | Class(es) to apply to the `svg` element where the classes are inserted as "class" in the following template: `#!py3 '%(class)s-%(unicode)s'`.
`image_path` | string | `#!py3 ''`              | Path to the SVG sprites.

pymdownx.emoji.to_awesome : This generator is another EmojiOne specific output called EmojiOne Awesome. It aims to give a font-awesome like interface for EmojiOne. The emojione-awesome CDN currently follows this format: https://cdn.jsdelivr.net/npm/emojione@3.1.2/extras/css/emojione-awesome.css, so update accordingly. The output format is:

```html
<i class="e1a-smile"></i>
```

**Generator Specific Options**

Option       | Type       | Default      | Description
------------ | ---------- | ------------ | -----------
`classes`    | string     | `#!py3 'e1a'` | Class(es) to apply to the element where the classes are inserted as "class" in the following template: `#!py3 '%(class)s-%(shortname)s'`.
`attributes` | dictionary | `#!py3 {}`    | A dictionary containing tag attributes as key value string pairs. The dictionary keys are the attribute names and dictionary values are the attribute values.

pymdownx.emoji.to_alt : This generator supports all emoji indexes. The generator outputs the alt value directly to the document. The output can be Unicode characters, HTML entities, or even just the short name depending on what the global setting of alt is set to.

```html
😃
```

There are no generator specific options.

自定义Emoji工业

In order to provide a custom index, the Emoji extension must be given a function that returns a suitable emoji index. No parameters are passed to the function. The function should simply return the custom index in the following format.

emoji_index = {
    # Name is the name of the index.  This is passed into the emoji
    # generator functions and can be used to differentiate logic
    # for different indexes if required.
    "name": "myindex",

    # The actual index.  A dictionary of all the emoji.
    # Different emoji short names with the same Unicode data
    # can be mentioned under aliases.
    "emoji": {
        # Key is the short name.
        ":zero:": {

            # Name is the long name.
            "name": "keycap digit zero",

            # Category of emoji.
            # Not needed if this is a non-Unicode, custom
            # emoji with no category
            "category": "symbol",

            # Unicode is the representation of the Unicode
            # code points, but it is not necessarily valid Unicode
            # code points. Essentially it is what represents the Unicode
            # and is used as the image name for pngs and svgs. Depending
            # on the index, it may not be code points alt all. It is also
            # sometimes used as part of special class names in the HTML
            # output (depending on the generator).
            #
            # In the case of Gemoji and EmojiOne this is the Unicode code
            # points with variations and joiners striped out. In the case of
            # Twemoji, it is usually full valid code points though leading
            # zeros are stripped from the beginning.
            #
            # Do not include this if the emoji is a custom, non-Unicode emoji.
            "unicode": "0030-20e3",

            # This is the full Unicode code points and is
            # used for the "alt" attributes in the HTML output of images.
            # It is redundant to include this if it is the
            # same as 'unicode', but it won't hurt anything if it is.
            #
            # Do not include this if the emoji is a custom,
            # non-Unicode emoji. This shows a fully qualified emoji code,
            # but it could just as easily be "0030-2033" which is also valid.
            # Some indexes will provide fully qualified, some may not.
            "unicode_alt": "0030-fe0f-20e3"
        },
        # No need to specify 'unicode_alt' as it is the same
        # as 'unicode'.
        ":thumbsup:": {
            "name": "thumbs up sign",
            "unicode": "1f44d",
            "category": "people"
        },
        # Should not specify any unicode fields
        # as this is not a real unicode emoji.
        ":octocat:": {
            "name": "octocat"
        },
    },
    # Short names that share previously defined Unicode data
    # like '+1' and 'thumbsup' etc.
    "aliases": {
        # Key is the alias.
        # Value is the short name it maps to in the
        # previously defined 'emoji' key.
        ":+1:": ":thumbsup:"
    }
}

自定义Emoji生成器

Each different kind of output is controlled by a different emoji generator function, but all generator functions have the same input format. The format is shown below in case you need to create your own custom output generator.

def emoji_generator(index, shortname, alias, uc, alt, title, category, options, md) :

Parameter   | Type       |Description
----------- | ---------- | ----------
`index`     | string     | The name of the selected emoji index.
`shortname` | string     | The current short name.  This may differ from the actual name used in a document as aliases get translated to the main short name.
`alias`     | string     | If the specified short name is an alias, that alias will be set here, and the main short name will be found under `shortname`.  This will be `None` if the name used was not an alias.
`uc`        | string     | This is a string representation of the Unicode, it could technically be anything as this is normally used to reference image files. So while some indexes will have this be code points, it may not contain code points at all or it may strip out code points for simpler image names. So the value here will not always be practical for calculating the actual Unicode points of an emoji.  This will be `None` for non-standard emoji that are not Unicode.
`alt`       | string     | This is the alternative emoji value (or fallback value).  Its format will differ depending on the extension setting `alt` and also the index being used. This will be returned as either the full valid Unicode characters or HTML entities, or it will be the short name used.  See the `alt` setting for more info.
`title`     | string     | This is the title that can be used in image elements.  Depending on the global extension setting `title`, this will either return the full long description, the short name, or `None`.  See the `title` setting for more info.
`category`  | string     | Category of the emoji, or `None` if there is no category for the emoji.
`options`   | dictionary | This is a dictionary to specify generator function specific options.  This can be anything, and it is up to the generator function to parse and provide defaults.
`md`        | class      | This is the Markdown class object.  This is mainly used to access specific things needed from the Markdown class when formatting your output.  If you needed to stash your output, you would do something like: `#!py3 md.htmlStash.store(alt, safe=True)`.

!!! Warning "Non-Unicode emoji"
    Keep in mind that Gemoji ships with some non-standard emoji like `:octocat:` that do not have Unicode code points.  `uc` and `alt` are affected by this and will return `None` and the short name respectively instead of strings describing the Unicode points.  For example `:octocat:` will just return `None` for `uc` and `:octocat:` for `alt`.  If you are parsing an index with custom emoji, like Gemoji has, then you need to be aware of this.

使用MkDocs

This project uses these extensions with MkDocs to generate the documentation. It might not be obvious how to set the index or generator functions in MkDocs' YAML settings file, but it is actually pretty easy. The functions are referenced like you would import them in Python except you also append them with a special prefix to let the YAML module know that the setting value is a Python object. For instance, to specify the to_svg generator, you would simply reference it like this: !!python/name:pymdownx.emoji.to_svg (or you could use your own custom module ).

markdown_extensions:
  - pymdownx.emoji:
      emoji_generator: !!python/name:pymdownx.emoji.to_svg

Emoji索引更新

The Emoji extension might at times be behind on having indexes built from the latest repositories. We try to keep the indexes updated with new releases, but if they fall out of date, you can open an issue on the this project's issue page to alert the maintainer(s) and they will update them when someone gets a chance. Pull requests are also welcome. The process for updating the indexes is automated, so it is fairly easy to do a pull request. See Generating Emoji Indexes for more info.

选项

Option	Type	Default	Description
emoji_index	function	emojione index	A function that returns the index to use when parsing :short_name: syntax. See Default Emoji Indexes to see the provided indexes.
emoji_generator	function	to_png generator	A function that takes the emoji info and constructs the desired emoji output. See Default Emoji Generators to see the provided generators.
title	string	'short'	Specifies the title format that is fed into the emoji generator function. Can either be long which is the long description of the emoji, short which is the short name (:short:), or none which will simply pass None.
alt	string	'unicode'	Specifies the format for the alt value that is passed to the emoji generator function. If alt is set to short, the short name will be passed to the generator. If alt is set to unicode the Unicode characters are passed to the generator. Lastly, if alt is set to html_entity, the Unicode characters are passed encoded as HTML entities.
remove_variation_selector	bool	False	Specifies whether variation selectors should be removed from Unicode alt. Currently, only fe0f is removed as it is the only one presently found in the current emoji sets.
options	dictionary	{}	Options that are specific to emoji generator functions. Supported parameters can vary from function to function.

Legacy GitHubEmoji Emulation

The Emoji extension was actually created to replace the now retired GitHubEmoji extension. Emoji was written to be much more flexible. If you have a desire to configure the output to be like the legacy GitHubEmoji extension, you can use the settings below. This shows the full setup. To learn more about the settings used, continue reading the documentation.

import pymdownx.emoji

extension_configs = {
    "pymdownx.emoji": {
        "emoji_index": pymdownx.emoji.gemoji,
        "emoji_generator": pymdownx.emoji.to_png,
        "alt": "short",
        "options": {
            "attributes": {
                "align": "absmiddle",
                "height": "20px",
                "width": "20px"
            },
            "image_path": "https://assets-cdn.github.com/images/icons/emoji/unicode/",
            "non_standard_image_path": "https://assets-cdn.github.com/images/icons/emoji/"
        }
    }
}