Pelican plugins » Links and other

m.css plug­ins make link­ing to ex­ter­nal con­tent al­most too easy. If your web­site is about cod­ing, chances are quite high that you will be link­ing to repos­i­to­ries, doc­u­men­ta­tion or bug­track­ers. Man­u­al­ly copy-past­ing links from the brows­er gets quite an­noy­ing af­ter a while and al­so doesn’t re­al­ly help with keep­ing the reST sources read­able.

Be­cause not ev­ery­body needs to link to all ser­vices pro­vid­ed here, the func­tion­al­i­ty is sep­a­rat­ed in­to a bunch of sep­a­rate plug­ins, each hav­ing its own re­quire­ments.

GitHub

Down­load the m/gh.py file, put it in­clud­ing the m/ di­rec­to­ry in­to one of your PLUGIN_PATHS and add m.gh pack­age to your PLUGINS in pelicanconf.py:

PLUGINS += ['m.gh']

Use the :gh: in­ter­pret­ed text role for link­ing. The plug­in mim­ics how GitHub Fla­vored Mark­down pars­es in­ter-site links, with some ex­ten­sions on top. In ad­di­tion to well-known ref­er­ences to com­mits and is­sues/PRs via @ and #, $ is for link­ing to a tree (or file in giv­en tree) and ^ is for link­ing to a tag/re­lease. If your link tar­get doesn’t con­tain any of these char­ac­ters and con­tains more than one slash, the tar­get is sim­ply prepend­ed with https://github.com/.

Link text is equal to link tar­get for repos­i­to­ry, com­mit and is­sue/PR links, oth­er­wise the full ex­pand­ed URL is used. Sim­i­lar­ly to builtin link­ing func­tion­al­i­ty, if you want a cus­tom text for a link, use the :gh: syn­tax.

-   Profile link: :gh:`mosra`
-   Repository link: :gh:`mosra/m.css`
-   Commit link: :gh:`mosra/m.css@4d362223f107cffd8731a0ea031f9353a0a2c7c4`
-   Issue/PR link: :gh:`mosra/magnum#123`
-   Tree link: :gh:`mosra/m.css$next`
-   Tag link: :gh:`mosra/magnum^snapshot-2015-05`
-   File link: :gh:`mosra/m.css$master/css/m-dark.css`
-   Arbitrary link: :gh:`mosra/magnum/graphs/contributors`
-   :gh:`Link with custom title <getpelican/pelican>`

OpenGL func­tions and ex­ten­sions

Down­load the m/gl.py file, put it in­clud­ing the m/ di­rec­to­ry in­to one of your PLUGIN_PATHS and add m.gl pack­age to your PLUGINS in pelicanconf.py:

PLUGINS += ['m.gl']

Use the :glfn: in­ter­pret­ed text role for link­ing to func­tions, :glext: for link­ing to OpenGL / OpenGL ES ex­ten­sions, :webglext: for link­ing to We­bGL ex­ten­sions and :glfnext: for link­ing to ex­ten­sion func­tions. In the link tar­get the lead­ing gl pre­fix of func­tions and the lead­ing GL_ pre­fix of ex­ten­sions is prepend­ed au­to­mat­i­cal­ly.

Link text is equal to full func­tion name in­clud­ing the gl pre­fix and () for func­tions, equal to ex­ten­sion name or equal to ex­ten­sion func­tion link, in­clud­ing the ven­dor suf­fix. For :glfn:, :glext: and :webglext: it’s pos­si­ble to spec­i­fy al­ter­nate link text us­ing the well-known syn­tax.

-   Function link: :glfn:`DispatchCompute`
-   Extension link: :glext:`ARB_direct_state_access`
-   WebGL extension link: :webglext:`OES_texture_float`
-   Extension function link: :glfnext:`SpecializeShader <ARB_gl_spirv>`
-   :glfn:`Custom link title <DrawElementsIndirect>`

Doxy­gen doc­u­men­ta­tion

Down­load the m/dox.py file, put it in­clud­ing the m/ di­rec­to­ry in­to one of your PLUGIN_PATHS and add m.dox pack­age to your plug­ins in pelicanconf.py. The plug­in us­es Doxy­gen tag files to get a list of link­able sym­bols and you need to pro­vide list of 3-tu­ples con­tain­ing tag file path, URL pre­fix and list of im­plic­it­ly prepend­ed names­paces in M_DOX_TAGFILES con­fig­u­ra­tion to make the plug­in work. Ex­am­ple con­fig­u­ra­tion:

PLUGINS += ['m.dox']
M_DOX_TAGFILES = [
    ('doxygen/corrade.tag', 'http://doc.magnum.graphics/corrade/', ['Corrade::']),
    ('doxygen/magnum.tag', 'http://doc.magnum.graphics/magnum/', ['Magnum::'])]

Use the :dox: in­ter­pret­ed text role for link­ing to doc­u­ment­ed sym­bols. All link tar­gets un­der­stood by Doxy­gen’s @ref or @link com­mands are un­der­stood by this plug­in as well, in ad­di­tion it’s pos­si­ble to link to the doc­u­men­ta­tion in­dex page by spec­i­fy­ing the tag file base­name w/o ex­ten­sion as link tar­get. In or­der to save you some typ­ing, the lead­ing names­pace(s) men­tioned in the M_DOX_TAGFILES set­ting can be omit­ted when link­ing to giv­en sym­bol.

Link text is equal to link tar­get in all cas­es ex­cept for pages and sec­tions, where page/sec­tion ti­tle is ex­tract­ed from the tag­file. It’s pos­si­ble to spec­i­fy cus­tom link ti­tle us­ing the :dox: syn­tax. If a sym­bol can’t be found, a warn­ing is print­ed to out­put and link tar­get is ren­dered in monospace font (or, if cus­tom link ti­tle is spec­i­fied, just the ti­tle is ren­dered, as nor­mal text). You can ap­pend #anchor to link-target to link to an­chors that are not present in the tag file (such as #details for the de­tailed docs or #pub-methods for jump­ing straight to a list of pub­lic mem­ber func­tions), the same works for query pa­ram­e­ters start­ing with ?.

-   Function link: :dox:`Utility::Directory::mkpath()`
-   Class link: :dox:`Interconnect::Emitter`
-   Page link: :dox:`building-corrade`
-   :dox:`Custom link title <testsuite>`
-   :dox:`Link to documentation index page <corrade>`
-   :dox:`Link to an anchor <Interconnect::Emitter#pub-methods>`

Ab­bre­vi­a­tions

While not ex­act­ly a link but rather a way to pro­duce cor­rect <abbr> el­e­ments, it be­longs here as it shares a sim­i­lar syn­tax.

Down­load the m/ab­br.py file, put it in­clud­ing the m/ di­rec­to­ry in­to one of your PLUGIN_PATHS and add m.abbr pack­age to your PLUGINS in pelicanconf.py. This plug­in as­sumes pres­ence of m.html­san­i­ty.

PLUGINS += ['m.htmlsanity', 'm.abbr']

The plug­in over­rides the builtin Pel­i­can ab­br in­ter­pret­ed text role and makes its syn­tax con­sis­tent with oth­er com­mon roles of reST and m.css.

Use the :abbr: in­ter­pret­ed text role for cre­at­ing ab­bre­vi­a­tions with ti­tle in an­gle brack­ets:

:abbr:`HTML <HyperText Markup Language>` and :abbr:`CSS <Cascading Style Sheets>`
are *all you need* for producing rich content-oriented websites.

HTML and CSS are all you need for pro­duc­ing rich con­tent-ori­ent­ed web­sites.

File size queries

Okay, this is not a link at all, but — some­times you might want to dis­play size of a file, for ex­am­ple to tell the users how big the down­load will be.

Down­load the m/file­size.py file, put it in­clud­ing the m/ di­rec­to­ry in­to one of your PLUGIN_PATHS and add m.filesize pack­age to your PLUGINS in pelicanconf.py.

PLUGINS += ['m.filesize']

Use the filesize in­ter­pret­ed text role to dis­play the size of a file in­clud­ing units. The filesize-gz role com­press­es the file us­ing GZip first be­fore cal­cu­lat­ing the size.

The compiled ``m-dark.compiled.css`` CSS file has
:filesize:`{filename}/../css/m-dark.compiled.css` but only
:filesize-gz:`{filename}/../css/m-dark.compiled.css` when the server
sends it compressed.

The com­piled m-dark.compiled.css CSS file has 60.2 kB but on­ly 9.1 kB when the serv­er sends it com­pressed.

Alias­es

Site con­tent al­most nev­er stays on the same place for ex­tend­ed pe­ri­ods of time and pre­serv­ing old links for back­wards com­pat­i­bil­i­ty is a vi­tal thing for us­er friend­li­ness. This plug­in al­lows you to cre­ate a re­di­rect alias URLs for your pages and ar­ti­cles.

Down­load the m/alias.py file, put it in­clud­ing the m/ di­rec­to­ry in­to one of your PLUGIN_PATHS and add m.alias pack­age to your PLUGINS in pelicanconf.py. This plug­in as­sumes pres­ence of m.html­san­i­ty.

PLUGINS += ['m.htmlsanity', 'm.alias']

Use the :alias: field to spec­i­fy one or more lo­ca­tions that should re­di­rect to your ar­ti­cle / page. Each line is treat­ed as one alias, the lo­ca­tions have to be­gin with / and are rel­a­tive to the Pel­i­can out­put di­rec­to­ry, each of them con­tains just a <meta http-equiv="refresh" /> that points to a ful­ly-qual­i­fied URL of the ar­ti­cle or page.

If the alias ends with /, the redi­rec­tor file is saved in­to index.html in giv­en di­rec­to­ry.

My Article
##########

:alias:
    /2018/05/06/old-version-of-the-article/
    /even-older-version-of-the-article.html