Plugins » Metadata

As­signs ad­di­tion­al de­scrip­tion and im­ages to cat­egor­ies, au­thors and tags in Pel­ic­an-powered sites. As it ex­tends a Pel­ic­an-spe­cif­ic fea­ture, it has no equi­val­ent for oth­er themes.

How to use

Down­load the m/metadata.py file, put it in­clud­ing the m/ dir­ect­ory 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­erly rendered, it’s ad­vised to add the new fields to FORMATTED_FIELDS:

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

This plu­gin parses ad­di­tion­al info from pages in sub­dir­ect­or­ies of the con­tents dir­ect­ory (i.e., where the PATH set­ting points to). By de­fault, the dir­ect­or­ies are as fol­lows and can be con­figured with these set­tings:

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

The m.css Pel­ic­an theme re­cog­nizes pres­ence of this plu­gin and renders the ad­di­tion­al metadata both in the page and in the Open Graph and Twit­ter Card so­cial <meta> tags, in ad­di­tion to tags rendered by art­icles them­selves. See be­low for more in­form­a­tion.

Au­thor metadata

Au­thor pages are matched to au­thors based on the slug (so e.g. metadata for au­thor named John Doe will be in a file named authors/john-doe.rst). The fol­low­ing metadata are re­cog­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­ic­an theme. If not set, no au­thor de­tails block is rendered.
  • Page title is ex­posed to the theme in author.page.title on the au­thor page and in article.author.badge_title in all art­icles hav­ing giv­en au­thor. In the m.css Pel­ic­an 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 provide a longer ver­sion of au­thor name on this page. If not set, the m.css Pel­ic­an theme uses the glob­al au­thor name (the one set by art­icles) in­stead — but note that since 3.8, Pel­ic­an will warn about this and sug­gest to spe­cify the title ex­pli­citly.
  • The :description: field is ex­posed to the theme in author.page.description on the au­thor page. The m.css Pel­ic­an theme uses it in <meta name="description">. If not set, no tag is rendered.
  • The :summary: field is ex­posed to the theme in author.page.summary on the au­thor page. The m.css Pel­ic­an theme uses it in og:description / twitter:description so­cial <meta> tag. If not set, no tag is rendered.
  • The :badge: field is ex­posed to the theme in article.author.badge in all art­icles hav­ing giv­en au­thor. The m.css Pel­ic­an theme uses it to dis­play an About the au­thor badge at the end of art­icle pages. Sim­il­arly to page con­tent, it’s pos­sible to use ad­vanced reST format­ting cap­ab­il­it­ies here. If not set, no badge at the end of au­thor’s art­icles is rendered.
  • 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 art­icles hav­ing giv­en au­thor. The m.css Pel­ic­an theme uses it to add an im­age to au­thor badge on art­icles, 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­pec­ted to be smal­ler and square sim­il­arly to the M_SOCIAL_IMAGE de­scribed in the theme doc­u­ment­a­tion. If not set, the de­tails and badges are rendered without im­ages and no so­cial tag is present. Does not af­fect twitter:card, it’s set to summary re­gard­less of wheth­er 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­ic­an theme uses it to render twitter:creator / twitter::creator:id so­cial <meta> tags. If not set, no tags are rendered.

Ex­ample of a com­pletely 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: {static}/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­egory metadata

Cat­egory pages are matched to cat­egor­ies based on the slug (so e.g. metadata for cat­egory named Guest posts will be in a file named categories/guest-posts.rst). The fol­low­ing metadata are re­cog­nized:

  • Page con­tent is ex­posed to the theme in category.page.content on the cat­egory page and used to fill cat­egory de­tails block on top of the cat­egory page in the m.css Pel­ic­an theme. If not set, no cat­egory de­tails block is rendered.
  • Page title is ex­posed to the theme in category.page.title on the cat­egory page and in article.category.badge_title in all art­icles be­ing in giv­en cat­egory. In the m.css Pel­ic­an theme it is used as cap­tion in cat­egory de­tails block, in og:title / twitter:title so­cial <meta> tag on cat­egory page and as badge title on art­icle pages. Can be used to provide a longer ver­sion of cat­egory name for art­icle badge and de­tailed cat­egory info. If not set, the m.css Pel­ic­an theme uses the glob­al cat­egory name (the one set by art­icles) in­stead — but note that since 3.8, Pel­ic­an will warn about this and sug­gest to spe­cify the title ex­pli­citly.
  • The :description: field is ex­posed to the theme in category.page.description on the cat­egory page. The m.css Pel­ic­an theme uses it in <meta name="description">. If not set, no tag is rendered.
  • The :summary: field is ex­posed to the theme in category.page.summary on the cat­egory page. The m.css Pel­ic­an theme uses it in og:description / twitter:description so­cial <meta> tag. If not set, no tag is rendered.
  • The :badge: field is ex­posed to the theme in article.category.badge in all art­icles be­ing in giv­en cat­egory. The m.css Pel­ic­an theme uses it to dis­play an in­form­a­tion­al badge at the end of art­icle pages. Sim­il­arly to page con­tent, it’s pos­sible to use ad­vanced reST format­ting cap­ab­il­it­ies here. If not set, no badge at the end of art­icles in giv­en cat­egory is rendered.
  • The :image: field is ex­posed to the theme in category.page.image on the cat­egory page and in article.category.image in all art­icles be­ing in giv­en cat­egory. The m.css Pel­ic­an theme uses it to add an im­age to cat­egory badges on art­icles, to cat­egory de­tails on cat­egory page and in og:image / twitter:image so­cial <meta> tags on cat­egory page. If art­icle cov­er im­age is not spe­cified, the im­age is used also for og:image / twitter:image on giv­en art­icle, over­rid­ing the glob­al M_SOCIAL_IMAGE. It’s ex­pec­ted to be smal­ler and square sim­il­arly to the M_SOCIAL_IMAGE de­scribed in the theme doc­u­ment­a­tion. If not set, the de­tails and badges are rendered without 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 only on pres­ence of art­icle cov­er im­age.

Ex­ample of a com­pletely filled cat­egory page, saved un­der categories/guest-posts.rst and match­ing a cat­egory named Guest posts:

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

:image: {static}/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 metadata

Tag pages are matched to au­thors based on the slug (so e.g. metadata for tag named Pan­to­mime will be in a file named tags/pantomime.rst). The fol­low­ing metadata are re­cog­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­ic­an theme. If not set, no tag de­tails block is rendered.
  • Page title 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 provide a longer ver­sion of tag name on this page. If not set, the m.css Pel­ic­an theme uses the glob­al tag name (the one set by art­icles) in­stead — but note that since 3.8, Pel­ic­an will warn about this and sug­gest to spe­cify the title ex­pli­citly.
  • The :description: field is ex­posed to the theme in tag.page.description on the tag page. The m.css Pel­ic­an theme uses it in <meta name="description">. If not set, no <meta> tag is rendered.
  • The :summary: field is ex­posed to the theme in tag.page.summary on the tag page. The m.css Pel­ic­an theme uses it in og:description / twitter:description so­cial <meta> tag. If not set, no <meta> tag is rendered.

Ex­ample of a com­pletely filled tag page, saved un­der tags/pantomime.rst and match­ing a tag named Pan­to­mime:

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

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

¯\_(ツ)_/¯