Package: yafg
yafg - Yet Another Figure Generatoryafgis yet another figure generator plugin for Python's Markdown. It's
written and tested with Python 2.7 and Python 3.6 as well as Markdown 3.1.1, but
aims at supporting as many versions as possible. If you encounter any problems
with the given versions or find yourself usingyafgwithout problems with any
others, please give me a hint using the e-mail address listed below.It uses thetitleattribute given to an image within Markdown to generate a<figure>environment with a<figcaption>containing thetitle's text,
e.g.:![Alt text](/path/to/image.png "This is the title of the image.")becomes<figure><imgalt="Alt text"src="/path/to/image.png"title="This is the title of the image."/><figcaption>This is the title of the image.</figcaption></figure>How?Installyafgcan be installed via PyPI using:pip install yafgStandard UsageWhen parsing your input, you can addyafgto Markdown as follows:importyafg# ...outputString=markdown.markdown(inputString,extensions=[yafg.YafgExtension(stripTitle=False)])PelicanPelican users can addyafgto their generator process by adding it to theMARKDOWNvariable in thepelicanconf.pyas follows:MARKDOWN={'extensions_configs':{'yafg':{'stripTitle':'False',},},}OptionsCurrently supported options are listed below:stripTitle(default:False):Removes the originaltitleattribute from the<img />element. Since its
usage is discouraged anyways (see below), this may be an option worth
considering.figureClass(default:""):The CSS class to add to the generated<figure />element.figcaptionClass(default:""):The CSS class to add to the generated<figcaption />element.figureNumbering(default:False):Adds a figure number like "Figure 1:" in front of the caption. It's wrapped
in a<span />for easier styling.figureNumberClass(default:""):The CSS class to add to the<span />element generated for the figure
number.figureNumberText(default:"Figure"):The text to show in front of the figure number. A final non-breaking space
is inserted between the content offigureNumberTextand the actual figure
number.Why?yafg arose from the dissatisfaction with the existing solutions, namely:markdown_captionswhich uses
thealtattribute for the<figcaption>.markdown-figcapwhich uses a
cryptic syntax that doesn't integrate well into Markdown, IMHO.figureAltCaptionwhich
cannot handle multi-line descriptions and uses thealtattribute for the<figcaption>.Using thealtattribute to fill the<figcaption>is not correct, becauseas
the standard states[...] the alternative text is a replacement for the image, not a description
[...]for the most common case of a text accompanied by an augmenting image. It should
be used for an exact reproduction of what can be seen on the image for those who
cannot see it, for example because they're blind or their internet connection is
too slow. A figure's caption in turn should provide a description helping to
understand the content of the image.Thetitleattribute on the other hand should contain "[a]dvisory information
associated with the element (W3C Core Attribute
List). This is rather vague
and often used by browser vendors to show tooltips containing the title. Since
tooltips are highly problematic for a11y reasons and the browser support varies,
"[r]elying on the title attribute is currently discouraged" (HTML Living
Standard).
This makes it an ideal candidate to store the wantedfigcaptioninside of the
standard Markdown syntax.Authoryafghas been written by:Philipp Trommleryafg@philipp-trommler.meLicenseyafghas been published under a GPL 3.0 or later license. See theLICENSEfile for more information.