pelican-plugins / linkclass Goto Github PK

Pelican plugin to set anchor tag's class attribute to differentiate between internal and external links

License: GNU Affero General Public License v3.0

Python 100.00%

linkclass's Introduction

Link Class: A Plugin for Pelican

This Pelican plugin allows you to set the class attribute of <a> elements (generated in Markdown by [ext](link)) according to whether the link is external (i.e., starts with http:// or https://) or internal to the Pelican-generated site.

For now, this plugin only works with Markdown. It has been tested with version 3.0+ of the Python-Markdown module and may not work with previous versions.

Installation

This plugin is available as a package at PyPI and can be installed via:

python -m pip install pelican-linkclass

Configuration

In order to avoid clashes with already-defined classes in the user CSS style sheets, it is possible to specify the name of the classes that will be used. They can be specified in the Pelican setting file with the LINKCLASS variable, which must be defined as a list of tuples, like this:

'LINKCLASS' = (('EXTERNAL_CLASS', 'name-of-the-class-for-external-links'),
               ('INTERNAL_CLASS', 'name-of-the-class-for-internal-links'))

The default values for EXTERNAL_CLASS and INTERNAL_CLASS are, respectively, 'external' and 'internal'.

Styling Hyperlinks

One of the possible uses of this plugins is for styling. Suppose that we have the following Markdown content in your article:

This is an [internal](internal) link and this is an
[external](http://external.com) link.

If the default configuration variable values are used, then one possible CSS setting could be:

a.external:before {
    content: url('../images/external-link.png');
    margin-right: 0.2em;
}

(The file external-link.png is also distributed with this plugin. To use it, copy it to the appropriate place in your web site source tree, for instance in theme/static/images/.)

Then, the result will look like the following:

Note that this plugin also works with reference-style links, as in the following example:

This is an [internal][internal] link and this is an
[external][external] link.

 [internal]: internal
 [external]: http://external.com

Contributing

Contributions are welcome and much appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting on existing issues.

To start contributing to this plugin, review the Contributing to Pelican documentation, beginning with the Contributing Code section.

Acknowledgments

Many thanks to Yuliya Bagriy for setting up the package for PyPI, to Lucas Cimon for fixing the issues with pytest, and to Justin Mayer for helping with migration of this plugin under the Pelican Plugins organization.

Author

License

This project is released under the terms of the GNU Affero Public License, version 3 or later.

linkclass's People

Contributors

Stargazers

Watchers

Forkers

aviskase galaxy4public

linkclass's Issues

Wrong documentation for the configuration

This bug has been mentioned by GalaxyMaster in issue #32 : “the documented configuration does not match (and does not work) with the plugin. It requires three arguments instead of two in each tupple.”

This must be fixed.

Not detecting external named links

For example, this markdown:

This is an [external link][my_url].

[my_url]: https://github.com/rlaboiss/pelican-linkclass/

The URL is external, but it doesn't get tagged as such.

PyPI packaging

Hi! What do you think about making this plugin available through PyPI?

Or, if you don't want to, are you ok with me publishing it?

Convert and release as namespace plugin

This issue tracks the conversion of Link Class to a namespace plugin.

convert to namespace plugin filesystem layout
ensure existing test suite passes
apply community code style standards
add CI/CD configuration
release new version to PyPI

Plugin is not importable

Hi all,

I am on Ubuntu 22.04 with Python 3.10 and Pip 24.0 and I have installed pelican-linkclass (python3 -m pip install --user pelican-linkclass) but it is not importable.

In an interpreter, this causes an ImportError:

from pelican.plugins import linkclass

whereas it works for the plugin search for example.

The distribution info of the plugin is sitting in ~/.local/lib/python3.10/site-packages with name pelican_linkclass-2.1.3.dist-info alongside other namespace plugins such as search and similar-posts which can be imported normally.
However, contrary to these other plugins, it is not present in the subdirectory pelican/plugins/. Accordingly, when running pelican -D, we see that it does not discover it in the namespace plugins.

What's causing this? One difference I see is that packaging was done with pdm for linkclass, whereas other plugins were packaged with poetry.

At the moment I have to clone this repository and manually copy the proper folder into the pelican installation to make it work.

Thanks a lot for your help.

Plugin is broken (compatibility with markdown package)

Due to Python-Markdown/markdown@d18c3d0#diff-797c6da32780122232df19c7a2e709ebL341, the classes LinkPattern and ReferencePattern are no longer found and building the pelican site fails.

The new classes are now called LinkInlineProcessor and ReferenceInlineProcessor, and their handleMatch() method requires one additional argument.

Support for SITEURL links to be recognised as "internal"

Currently, the logic is purely based on whether the link has "https?://" as the string prefix for href. However, there are quite a few sites that use SITEURL Pelican setting to define the full URL for the generated internal links (this is mostly needed to support things like the sitemap plugin and others). When SITEURL is defined, this plugin would mark all links as external, which kind of renders it useless in these configurations.