Plugins » Links and other

Stylable links

For Pel­ic­an, down­load the m/link.py file, put it in­clud­ing the m/ dir­ect­ory in­to one of your PLUGIN_PATHS and add m.link pack­age to your PLUGINS in pelicanconf.py. For the Py­thon doc theme, it’s enough to just list it in PLUGINS:

PLUGINS += ['m.link']

The :link: in­ter­preted text role is an al­tern­at­ive to the built­in reST link syn­tax, but with an abil­ity to spe­cify ad­di­tion­al CSS classes. At the mo­ment the plu­gin knows only ex­tern­al URLs.

.. role:: link-flat-big(link)
    :class: m-flat m-text m-big

:link-flat-big:`Look here, this is great! <https://mcss.mosra.cz>`

Git­Hub

For Pel­ic­an, down­load the m/gh.py file, put it in­clud­ing the m/ dir­ect­ory in­to one of your PLUGIN_PATHS and add m.gh pack­age to your PLUGINS in pelicanconf.py. For the Py­thon doc theme, it’s enough to just list it in PLUGINS:

PLUGINS += ['m.gh']

Use the :gh: in­ter­preted text role for link­ing. The plu­gin mim­ics how Git­Hub Flavored Mark­down parses inter-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 simply pre­pen­ded with https://github.com/.

Link text is equal to link tar­get for re­pos­it­ory, com­mit and is­sue/PR links, oth­er­wise the full ex­pan­ded URL is used. Sim­il­arly to built­in link­ing func­tion­al­ity, if you want a cus­tom text for a link, use the :gh:`link text <link-target>` syn­tax. It’s also pos­sible to add cus­tom CSS classes by de­riv­ing the role and adding the :class: op­tion.

.. role:: gh-flat(gh)
    :class: m-flat

-   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>`
-   Flat link: :gh-flat:`mosra`

OpenGL func­tions and ex­ten­sions

For Pel­ic­an, down­load the m/gl.py file, put it in­clud­ing the m/ dir­ect­ory in­to one of your PLUGIN_PATHS and add m.gl pack­age to your PLUGINS in pelicanconf.py. For the Py­thon doc theme, it’s enough to just list it in PLUGINS:

PLUGINS += ['m.gl']

Use the :glfn: in­ter­preted text role for link­ing to func­tions, :glext: for link­ing to OpenGL / OpenGL ES ex­ten­sions, :webglext: for link­ing to WebGL 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 pre­pen­ded auto­mat­ic­ally.

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 vendor suf­fix. For :glfn:, :glext: and :webglext: it’s pos­sible to spe­cify al­tern­ate link text us­ing the well-known syn­tax. Adding cus­tom CSS classes can be done by de­riv­ing the role and adding the :class: op­tion.

.. role:: glfn-flat(glfn)
    :class: m-flat

-   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>`
-   Flat link: :glfn-flat:`DrawElements`

Vulkan func­tions and ex­ten­sions

For Pel­ic­an, down­load the m/vk.py file, put it in­clud­ing the m/ dir­ect­ory in­to one of your PLUGIN_PATHS and add m.vk pack­age to your PLUGINS in pelicanconf.py. For the Py­thon doc theme, it’s enough to just list it in PLUGINS:

PLUGINS += ['m.vk']

Use the :vkfn: in­ter­preted text role for link­ing to func­tions, :vktype: for link­ing to types and :vkext: for link­ing to ex­ten­sions. In the link tar­get the lead­ing vk pre­fix of func­tions, Vk pre­fix of types and the lead­ing VK_ pre­fix of ex­ten­sions is pre­pen­ded auto­mat­ic­ally.

Link text is equal to full func­tion name in­clud­ing the vk pre­fix and () for func­tions, Vk pre­fix for types or equal to ex­ten­sion name. It’s pos­sible to spe­cify al­tern­ate link text us­ing the well-known syn­tax.

.. role:: vkfn-flat(vkfn)
    :class: m-flat

-   Function link: :vkfn:`CreateInstance`
-   Type link: :vktype:`InstanceCreateInfo`
-   Definition link: :vktype:`VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO <StructureType>`
-   Extension link: :vkext:`KHR_swapchain`
-   :vkfn:`Custom link title <DestroyInstance>`
-   Flat link :vkfn-flat:`DestroyDevice`

Doxy­gen doc­u­ment­a­tion

For Pel­ic­an, down­load the m/dox.py file, put it in­clud­ing the m/ dir­ect­ory in­to one of your PLUGIN_PATHS and add m.dox pack­age to your plu­gins in pelicanconf.py. The plu­gin uses Doxy­gen tag files to get a list of link­able sym­bols and you need to provide list of tuples con­tain­ing tag file path, URL pre­fix, an op­tion­al list of im­pli­citly pre­pen­ded namespaces and an op­tion­al list of CSS classes for each link in a M_DOX_TAGFILES con­fig­ur­a­tion value. Ex­ample:

PLUGINS += ['m.dox']
M_DOX_TAGFILES = [
    ('doxygen/stl.tag', 'https://en.cppreference.com/w/'),
    ('doxygen/corrade.tag', 'https://doc.magnum.graphics/corrade/', ['Corrade::']),
    ('doxygen/magnum.tag', 'https://doc.magnum.graphics/magnum/', ['Magnum::'], ['m-text', 'm-flat'])]

For the Py­thon doc theme, the con­fig­ur­a­tion is the same. Tag file paths are re­l­at­ive to the con­fig­ur­a­tion file loc­a­tion or to PATH, if spe­cified.

Use the :dox: in­ter­preted text role for link­ing to doc­u­mented sym­bols. All link tar­gets un­der­stood by Doxy­gen’s @ref or @link com­mands are un­der­stood by this plu­gin as well, in ad­di­tion it’s pos­sible to link to the doc­u­ment­a­tion in­dex page by spe­cify­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 namespace(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 cases ex­cept for pages and sec­tions, where page/sec­tion title is ex­trac­ted from the tag­file. It’s pos­sible to spe­cify cus­tom link title us­ing the :dox:`link title <link-target>` syn­tax. If a sym­bol can’t be found, a warn­ing is prin­ted to out­put and link tar­get is rendered in a mono­space font (or, if cus­tom link title is spe­cified, just the title is rendered, 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 para­met­ers start­ing with ?. Adding cus­tom CSS classes can be done by de­riv­ing the role and adding the :class: op­tion.

.. role:: dox-flat(dox)
    :class: m-flat

-   Function link: :dox:`Utility::Path::make()`
-   Class link: :dox:`Containers::String`
-   Page link: :dox:`corrade-cmake`
-   :dox:`Custom link title <testsuite>`
-   :dox:`Link to documentation index page <corrade>`
-   :dox:`Link to an anchor <Containers::String#pub-methods>`
-   Flat link: :dox-flat:`plugin-management`

It’s also pos­sible to add cus­tom CSS classes via a fourth tuple item. For ex­ample, to make the links con­sist­ent with the Doxy­gen theme (where doc­u­ment­a­tion links are not un­der­scored, in­tern­al doxy­gen links are bold and ex­tern­al not), you could do this:

PLUGINS += ['m.dox']
M_DOX_TAGFILES = [
    ('doxygen/stl.tag', 'https://en.cppreference.com/w/', [],
        ['m-flat']),
    ('doxygen/your-lib.tag', 'https://doc.your-lib.com/', ['YourLib::'],
        ['m-flat', 'm-text', 'm-strong'])]

Ab­bre­vi­ations

While not ex­actly a link but rather a way to pro­duce cor­rect <abbr> ele­ments, it be­longs here as it shares a sim­il­ar syn­tax.

For Pel­ic­an, down­load the m/ab­br.py file, put it in­clud­ing the m/ dir­ect­ory in­to one of your PLUGIN_PATHS and add m.abbr pack­age to your PLUGINS in pelicanconf.py. This plu­gin as­sumes pres­ence of m.htmls­an­ity.

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

The plu­gin over­rides the built­in Pel­ic­an ab­br in­ter­preted text role and makes its syn­tax con­sist­ent with oth­er com­mon roles of reST and m.css.

Use the :abbr: in­ter­preted text role for cre­at­ing ab­bre­vi­ations with title in angle brack­ets. Adding cus­tom CSS classes can be done by de­riv­ing the role and adding the :class: op­tion.

.. role:: abbr-warning(abbr)
    :class: m-text m-warning

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

File size quer­ies

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

For Pel­ic­an, own­load the m/files­ize.py file, put it in­clud­ing the m/ dir­ect­ory 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­preted text role to dis­play the size of a file in­clud­ing units. The filesize-gz role com­presses the file us­ing GZip first be­fore cal­cu­lat­ing the size. Adding cus­tom CSS classes can be done by de­riv­ing the role and adding the :class: op­tion.

.. role:: filesize-yay(filesize-gz)
    :class: m-text m-success

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

Ali­ases

Site con­tent al­most nev­er stays on the same place for ex­ten­ded peri­ods of time and pre­serving old links for back­wards com­pat­ib­il­ity is a vi­tal thing for user friend­li­ness. This plu­gin al­lows you to cre­ate a re­dir­ect ali­as URLs for your pages and art­icles.

For Pel­ic­an, down­load the m/ali­as.py file, put it in­clud­ing the m/ dir­ect­ory in­to one of your PLUGIN_PATHS and add m.alias pack­age to your PLUGINS in pelicanconf.py.

PLUGINS += ['m.alias']

Use the :alias: field to spe­cify one or more loc­a­tions that should re­dir­ect to your art­icle / page. Each line is treated as one ali­as, the loc­a­tions have to be­gin with / and are re­l­at­ive to the Pel­ic­an out­put dir­ect­ory, each of them con­tains just a <meta http-equiv="refresh" /> that points to a fully-qual­i­fied URL of the art­icle or page.

If the ali­as ends with /, the re­dir­ect­or file is saved in­to index.html in giv­en dir­ect­ory.

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

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