Skip to content

A Sphinx extension, which overrides attributes of internal/external links.

License

Notifications You must be signed in to change notification settings

tatsushi-ikeda/sphinxcontrib-linkattr

Repository files navigation

CI License: MIT

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

About

A Sphinx extension, which overrides attributes of internal/external links.

Resources

License

Stars

Watchers

Forks

Packages

No packages published