Sphinx "linkattr" extension
Project description
sphinxcontrib-linkattr
A Sphinx extension, which overrides attributes of internal/external links.
Install
pip install sphinxcontrib-linkattr
Usage
Add sphinxcontrib.linkattr
in the extensions
list in conf.py
.
extensions += ['sphinxcontrib.linkattr']
Configuration
-
linkattr_attr_external
: (default:{'target': '_blank', 'rel': 'noreferrer noopener'}
)Attributes for external links. The default value implements open in new tab behavior for
html
builders. -
linkattr_suffix_external
: (default:None
)A string/object which is placed after the link texts of external links. Possible types of the value are
None
: Nothing.str
: String.dict
: This is interpreted as adoctutils.nodes
object, which class is'node'
element and properties are the rest elements (Seetests/fontawesome/conf.py
as an example).
-
linkattr_attr_internal
: (default:{}
)Attributes for internal links (See also
linkattr_attr_external
). -
linkattr_suffix_internal
: (default:None
)A string/object which is placed after the link texts of internal links (See also
linkattr_suffix_external
). -
linkattr_custom_translator_dict
: (default:{}
)A dictonary which has
format
:Translator object
pairs. If you want to use a custom builder class, this may be helpful.
Examples
-
A simple example with an open in new tab function and a suffix
[external link]
.- In
conf.py
extensions += ['sphinxcontrib.linkattr'] linkattr_suffix_external = ' [external link]'
- In
-
An example of the usage of
linkattr_suffix_external
as adoctutils.nodes
object, which has a Font Awesome icon.- In
conf.py
html_static_path = ['_static', '_static/css', '_static/webfonts'] html_css_files = ['css/fontawesome-all.css', 'custom.css'] extensions += ['sphinxcontrib.linkattr'] linkattr_suffix_external = dict(node='raw', format='html', text='<i class="fas fa-external-link-alt"></i>')
- In
_static/custom.css
i.fas.fa-external-link-alt { color: #AAAAAA; font-size: 0.8em; letter-spacing: 0.2em; margin-left: 0.2em; }
- You will need to download
fontawesome-*.zip
and placecss/fontawesome-all.css
andwebfonts/*
into_static/
(See also Hosting Font Awesome Yourself).
- In
-
tests/backgroundimage/: (demo)
An example of the usage of css with
.external
class andbackground-image
attribute. This is inspired by the method Wikipedia employs.- In
conf.py
extensions += ['sphinxcontrib.linkattr']
- In
_static/custom.css
.external { background-image: url(external_link.svg); background-position: center right; background-repeat: no-repeat; background-size: 16px, 16px; padding-right: 16px; }
- You will need to place an image file as
_static/external_link.svg
.
- In
License
MIT License
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinxcontrib-linkattr-0.2.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7ce3f56a7c8ce1f6c3d5a5c27f63ec411c4bd91033240a276603f778274d16e1 |
|
MD5 | aa154b252cacd5f51bf48b2682937027 |
|
BLAKE2b-256 | c74d6d42f0960171953f51939fca59c8066608211926d16f69353116af0cbf71 |
Hashes for sphinxcontrib_linkattr-0.2.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5c37ff8628fd2e4e7503bfc9481b0401b38b14c2cae55920e20fbaac5f022404 |
|
MD5 | 8b459cb78e49b42d77307fb25a26249c |
|
BLAKE2b-256 | 00c17a34ad6389ab33f926531f08d36f3fb1f821b13c546f2d248cf30ff8525e |