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 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 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.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | e699797fdc66308aa712c0f5820741a3b0fc8cbab69eeed973cd6a6b64f27ea8 |
|
MD5 | c5bbc5cea92438bc59cb5671a6eb5cab |
|
BLAKE2b-256 | 45644852a7324d2d827796866c0d969b34a4421a42048a61e0296f7982636d50 |
Hashes for sphinxcontrib_linkattr-0.2.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0635bca687ed60e50009c7a8764fc222e38b5c26e3676e1ce6607545a06fa839 |
|
MD5 | 7cc1818e5ff89472044bc0aa0db85200 |
|
BLAKE2b-256 | 10a17801f84efdee87c38220bc84603dd6cb47b454c363d0f383087e7ccf032e |