README.md

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 a doctutils.nodes object, which class is 'node' element and properties are the rest elements (See tests/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

• tests/simple/: (demo)

  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]'

• tests/fontawesome/: (demo)

  An example of the usage of linkattr_suffix_external as a doctutils.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 place css/fontawesome-all.css and webfonts/* into _static/ (See also Hosting Font Awesome Yourself).

• tests/backgroundimage/: (demo)

  An example of the usage of css with .external class and background-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.

License

MIT License