Pelican plugins » Metadata

As­signs ad­di­tion­al de­scrip­tion and im­ages to cat­e­gories, au­thors and tags.

How to use

Down­load the m/meta­da­ta.py file, put it in­clud­ing the m/ di­rec­to­ry in­to one of your PLUGIN_PATHS and add m.metadata pack­age to your PLUGINS in pelicanconf.py. In or­der to have the con­tents prop­er­ly ren­dered, it’s ad­vised to add the new fields to FORMATTED_FIELDS:

PLUGINS += ['m.metadata']
FORMATTED_FIELDS += ['description', 'badge']

This plug­in pars­es ad­di­tion­al in­fo from pages in sub­di­rec­to­ries of the con­tents di­rec­to­ry (i.e., where the PATH set­ting points to). By de­fault, the di­rec­to­ries are as fol­lows and can be con­fig­ured with these set­tings:

M_METADATA_AUTHOR_PATH = 'authors'
M_METADATA_CATEGORY_PATH = 'categories'
M_METADATA_TAG_PATH = 'tags'

The m.css Pel­i­can theme rec­og­nizes pres­ence of this plug­in and ren­ders the ad­di­tion­al meta­da­ta both in the page and in the Open Graph and Twit­ter Card so­cial <meta> tags, in ad­di­tion to tags ren­dered by ar­ti­cles them­selves. See be­low for more in­for­ma­tion.

Au­thor meta­da­ta

Au­thor pages are matched to au­thors based on the slug (so e.g. meta­da­ta for au­thor named John Doe will be in a file named authors/john-doe.rst). The fol­low­ing meta­da­ta are rec­og­nized:

  • Page con­tent is ex­posed to the theme in author.page.content on the au­thor page and used to fill au­thor de­tails block on top of the au­thor page in the m.css Pel­i­can theme. If not set, no au­thor de­tails block is ren­dered.
  • Page ti­tle is ex­posed to the theme in author.page.title on the au­thor page and in article.author.badge_title in all ar­ti­cles hav­ing giv­en au­thor. In the m.css Pel­i­can theme it is used as cap­tion in au­thor de­tails block and in og:title / twitter:title so­cial <meta> tag on au­thor page. Can be used to pro­vide a longer ver­sion of au­thor name on this page. If not set, the m.css Pel­i­can theme us­es the glob­al au­thor name (the one set by ar­ti­cles) in­stead — but note that since 3.8, Pel­i­can will warn about this and sug­gest to spec­i­fy the ti­tle ex­plic­it­ly.
  • The :description: field is ex­posed to the theme in author.page.description on the au­thor page. The m.css Pel­i­can theme us­es it in <meta name="description">. If not set, no tag is ren­dered.
  • The :summary: field is ex­posed to the theme in author.page.summary on the au­thor page. The m.css Pel­i­can theme us­es it in og:description / twitter:description so­cial <meta> tag. If not set, no tag is ren­dered.
  • The :badge: field is ex­posed to the theme in article.author.badge in all ar­ti­cles hav­ing giv­en au­thor. The m.css Pel­i­can theme us­es it to dis­play an About the au­thor badge at the end of ar­ti­cle pages. Sim­i­lar­ly to page con­tent, it’s pos­si­ble to use ad­vanced reST for­mat­ting ca­pa­bil­i­ties here. If not set, no badge at the end of au­thor’s ar­ti­cles is ren­dered.
  • The :image: field is ex­posed to the theme in author.page.image on the au­thor page and in article.author.image in all ar­ti­cles hav­ing giv­en au­thor. The m.css Pel­i­can theme us­es it to add an im­age to au­thor badge on ar­ti­cles, to au­thor de­tails on au­thor page and in og:image / twitter:image so­cial <meta> tags on au­thor page, over­rid­ing the glob­al M_SOCIAL_IMAGE. It’s ex­pect­ed to be small­er and square sim­i­lar­ly to the M_SOCIAL_IMAGE de­scribed in the theme doc­u­men­ta­tion. If not set, the de­tails and badges are ren­dered with­out im­ages and no so­cial tag is present. Does not af­fect twitter:card, it’s set to summary re­gard­less of whether the im­age is present or not.
  • The :twitter: / :twitter_id: fields are ex­posed to the theme in article.author.twitter / article.author.twitter_id and author.page.twitter / author.page.twitter_id. The m.css Pel­i­can theme us­es it to ren­der twitter:creator / twitter::creator:id so­cial <meta> tags. If not set, no tags are ren­dered.

Ex­am­ple of a com­plete­ly filled au­thor page, saved un­der authors/john-doe.rst and match­ing an au­thor named John Doe:

John "Not That Serial Killer" Doe
#################################

:twitter: @se7en
:twitter_id: 7777777
:image: {filename}/authors/john-doe.jpg
:description: I'm not that serial killer.
:summary: I'm really not that serial killer.
:badge: No, really, don't confuse me with that guy.

What? No, I didn't kill anybody. Yet.

Cat­e­go­ry meta­da­ta

Cat­e­go­ry pages are matched to cat­e­gories based on the slug (so e.g. meta­da­ta for cat­e­go­ry named Guest posts will be in a file named categories/guest-posts.rst). The fol­low­ing meta­da­ta are rec­og­nized:

  • Page con­tent is ex­posed to the theme in category.page.content on the cat­e­go­ry page and used to fill cat­e­go­ry de­tails block on top of the cat­e­go­ry page in the m.css Pel­i­can theme. If not set, no cat­e­go­ry de­tails block is ren­dered.
  • Page ti­tle is ex­posed to the theme in category.page.title on the cat­e­go­ry page and in article.category.badge_title in all ar­ti­cles be­ing in giv­en cat­e­go­ry. In the m.css Pel­i­can theme it is used as cap­tion in cat­e­go­ry de­tails block, in og:title / twitter:title so­cial <meta> tag on cat­e­go­ry page and as badge ti­tle on ar­ti­cle pages. Can be used to pro­vide a longer ver­sion of cat­e­go­ry name for ar­ti­cle badge and de­tailed cat­e­go­ry in­fo. If not set, the m.css Pel­i­can theme us­es the glob­al cat­e­go­ry name (the one set by ar­ti­cles) in­stead — but note that since 3.8, Pel­i­can will warn about this and sug­gest to spec­i­fy the ti­tle ex­plic­it­ly.
  • The :description: field is ex­posed to the theme in category.page.description on the cat­e­go­ry page. The m.css Pel­i­can theme us­es it in <meta name="description">. If not set, no tag is ren­dered.
  • The :summary: field is ex­posed to the theme in category.page.summary on the cat­e­go­ry page. The m.css Pel­i­can theme us­es it in og:description / twitter:description so­cial <meta> tag. If not set, no tag is ren­dered.
  • The :badge: field is ex­posed to the theme in article.category.badge in all ar­ti­cles be­ing in giv­en cat­e­go­ry. The m.css Pel­i­can theme us­es it to dis­play an in­for­ma­tion­al badge at the end of ar­ti­cle pages. Sim­i­lar­ly to page con­tent, it’s pos­si­ble to use ad­vanced reST for­mat­ting ca­pa­bil­i­ties here. If not set, no badge at the end of ar­ti­cles in giv­en cat­e­go­ry is ren­dered.
  • The :image: field is ex­posed to the theme in category.page.image on the cat­e­go­ry page and in article.category.image in all ar­ti­cles be­ing in giv­en cat­e­go­ry. The m.css Pel­i­can theme us­es it to add an im­age to cat­e­go­ry badges on ar­ti­cles, to cat­e­go­ry de­tails on cat­e­go­ry page and in og:image / twitter:image so­cial <meta> tags on cat­e­go­ry page. If ar­ti­cle cov­er im­age is not spec­i­fied, the im­age is used al­so for og:image / twitter:image on giv­en ar­ti­cle, over­rid­ing the glob­al M_SOCIAL_IMAGE. It’s ex­pect­ed to be small­er and square sim­i­lar­ly to the M_SOCIAL_IMAGE de­scribed in the theme doc­u­men­ta­tion. If not set, the de­tails and badges are ren­dered with­out im­ages and no so­cial tag is present. Does not af­fect twitter:card, it’s set to summary or summary_large_image de­pend­ing on­ly on pres­ence of ar­ti­cle cov­er im­age.

Ex­am­ple of a com­plete­ly filled cat­e­go­ry page, saved un­der categories/guest-posts.rst and match­ing a cat­e­go­ry named Guest posts:

Posts by our users
##################

:image: {filename}/categories/guest-posts.jpg
:description: User stories and product reviews
:summary: Stories of our users and honest reviews of our product.
:badge: This article is a guest post. Want to share your story as well? Head
    over to the `intro article <{filename}/blog/introducing-guest-posts.rst>`_
    to get to know more. We'll happily publish it here.

This section contains guest posts, reviews and success stories. Want to share
your story as well? Head over to the
`intro article <{filename}/blog/introducing-guest-posts.rst>`_ to get to know
more. We'll happily publish it here.

Tag meta­da­ta

Tag pages are matched to au­thors based on the slug (so e.g. meta­da­ta for tag named Pan­tomime will be in a file named tags/pantomime.rst). The fol­low­ing meta­da­ta are rec­og­nized:

  • Page con­tent is ex­posed to the theme in tag.page.content on the tag page and used to fill tag de­tails block on top of the tag page in the m.css Pel­i­can theme. If not set, no tag de­tails block is ren­dered.
  • Page ti­tle is ex­posed to the theme in tag.page.title on the tag page, is used as cap­tion in tag de­tails block on tag page and in og:title / twitter:title so­cial <meta> tag. Can be used to pro­vide a longer ver­sion of tag name on this page. If not set, the m.css Pel­i­can theme us­es the glob­al tag name (the one set by ar­ti­cles) in­stead — but note that since 3.8, Pel­i­can will warn about this and sug­gest to spec­i­fy the ti­tle ex­plic­it­ly.
  • The :description: field is ex­posed to the theme in tag.page.description on the tag page. The m.css Pel­i­can theme us­es it in <meta name="description">. If not set, no <meta> tag is ren­dered.
  • The :summary: field is ex­posed to the theme in tag.page.summary on the tag page. The m.css Pel­i­can theme us­es it in og:description / twitter:description so­cial <meta> tag. If not set, no <meta> tag is ren­dered.

Ex­am­ple of a com­plete­ly filled tag page, saved un­der tags/pantomime.rst and match­ing a tag named Pan­tomime:

¯\_(ツ)_/¯
##########

:description: ¯\_(ツ)_/¯
:summary: ¯\_(ツ)_/¯

¯\_(ツ)_/¯