GitHub Expand
logo Sphinx

Navegación

  • Documentation »
  • Using Sphinx »
  • Extensions »
  • sphinx.ext.extlinks – Markup to shorten external links

On this page

  • sphinx.ext.extlinks – Markup to shorten external links
    • extlinks
    • extlinks_detect_hardcoded_links

The Basics

  • Instalando Sphinx
  • Getting started
  • Build your first project

User guide

  • Using Sphinx
    • reStructuredText
    • Markdown
    • Cross-references
    • Configuration
    • Builders
    • Domains
    • Extensions
      • sphinx.ext.apidoc – Generate API documentation from Python packages
      • sphinx.ext.autodoc – Include documentation from docstrings
      • sphinx.ext.autosectionlabel – Allow referencing sections by their title
      • sphinx.ext.autosummary – Generate autodoc summaries
      • sphinx.ext.coverage – Recoge estadísticas de la cobertura de la documentación
      • sphinx.ext.doctest – Test snippets in the documentation
      • sphinx.ext.duration – Measure durations of Sphinx processing
      • sphinx.ext.extlinks – Markup to shorten external links
      • sphinx.ext.githubpages – Publicar documentación HTML en GitHub Pages
      • sphinx.ext.graphviz – Add Graphviz graphs
      • sphinx.ext.ifconfig – Include content based on configuration
      • sphinx.ext.imgconverter – A reference image converter using Imagemagick
      • sphinx.ext.inheritance_diagram – Include inheritance diagrams
      • sphinx.ext.intersphinx – Link to other projects” documentation
      • sphinx.ext.linkcode – Add external links to source code
      • Math support for HTML outputs in Sphinx
      • sphinx.ext.napoleon – Support for NumPy and Google style docstrings
      • sphinx.ext.todo – Support for todo items
      • sphinx.ext.viewcode – Add links to highlighted source code
    • HTML theming
    • Internacionalización
    • Soporte Web para Sphinx
  • Extending Sphinx
  • Sphinx API
  • Personalización de LaTex

Community

  • Get support
  • Contribute to Sphinx
  • Sphinx FAQ
  • Autores de Sphinx

Reference

  • Command-line tools
  • Configuration
  • Extensions
    • sphinx.ext.apidoc – Generate API documentation from Python packages
    • sphinx.ext.autodoc – Include documentation from docstrings
    • sphinx.ext.autosectionlabel – Allow referencing sections by their title
    • sphinx.ext.autosummary – Generate autodoc summaries
    • sphinx.ext.coverage – Recoge estadísticas de la cobertura de la documentación
    • sphinx.ext.doctest – Test snippets in the documentation
    • sphinx.ext.duration – Measure durations of Sphinx processing
    • sphinx.ext.extlinks – Markup to shorten external links
    • sphinx.ext.githubpages – Publicar documentación HTML en GitHub Pages
    • sphinx.ext.graphviz – Add Graphviz graphs
    • sphinx.ext.ifconfig – Include content based on configuration
    • sphinx.ext.imgconverter – A reference image converter using Imagemagick
    • sphinx.ext.inheritance_diagram – Include inheritance diagrams
    • sphinx.ext.intersphinx – Link to other projects” documentation
    • sphinx.ext.linkcode – Add external links to source code
    • Math support for HTML outputs in Sphinx
    • sphinx.ext.napoleon – Support for NumPy and Google style docstrings
    • sphinx.ext.todo – Support for todo items
    • sphinx.ext.viewcode – Add links to highlighted source code
  • reStructuredText
  • Glosario
  • Changelog
  • Proyectos usando Sphinx

sphinx.ext.extlinks – Markup to shorten external links¶

Autor del módulo: Georg Brandl

Added in version 1.0.

This extension is meant to help with the common pattern of having many external links that point to URLs on one and the same site, e.g. links to bug trackers, version control web interfaces, or simply subpages in other websites. It does so by providing aliases to base URLs, so that you only need to give the subpage name when creating a link.

Let’s assume that you want to include many links to issues at the Sphinx tracker, at https://github.com/sphinx-doc/sphinx/issues/num. Typing this URL again and again is tedious, so you can use extlinks to avoid repeating yourself.

The extension adds a config value:

extlinks¶
Type:
dict[str, tuple[str, str | None]]
Default:
{}

This config value must be a dictionary of external sites, mapping unique short alias names to a base URL and a caption. For example, to create an alias for the above mentioned issues, you would add

extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
                      'issue %s')}

Now, you can use the alias name as a new role, e.g. :issue:`123`. This then inserts a link to https://github.com/sphinx-doc/sphinx/issues/123. As you can see, the target given in the role is substituted in the base URL in the place of %s.

The link caption depends on the second item in the tuple, the caption:

  • If caption is None, the link caption is the full URL.

  • If caption is a string, then it must contain %s exactly once. In this case the link caption is caption with the partial URL substituted for %s – in the above example, the link caption would be issue 123.

To produce a literal % in either base URL or caption, use %%:

extlinks = {'KnR': ('https://example.org/K%%26R/page/%s',
                      '[K&R; page %s]')}

You can also use the usual «explicit title» syntax supported by other roles that generate links, i.e. :issue:`this issue <123>`. In this case, the caption is not relevant.

Distinto en la versión 4.0: Support to substitute by “%s” in the caption.

Nota

Since links are generated from the role in the reading stage, they appear as ordinary links to e.g. the linkcheck builder.

extlinks_detect_hardcoded_links¶
Type:
bool
Default:
False

If enabled, extlinks emits a warning if a hardcoded link is replaceable by an extlink, and suggests a replacement via warning.

Added in version 4.5.

Previous
sphinx.ext.duration – Measure durations of Sphinx processing
Next
sphinx.ext.githubpages – Publicar documentación HTML en GitHub Pages
© Copyright 2007-2025, the Sphinx developers. Creado usando Sphinx 8.3.0.