Link Processing

class ShortenLinkTransform(SphinxPostTransform):
    """
    Transform to shorten GitHub/GitLab links.
    
    Automatically processes external links to GitHub and GitLab repositories,
    converting full URLs to shortened, readable formats. Only transforms links
    where the display text matches the URL (meaning the user hasn't customized
    the link text).
    
    Attributes:
    - default_priority (int): Transform priority (400)
    - formats (tuple): Supported output formats ('html',)
    - supported_platform (ClassVar[dict]): Mapping of domains to platform names
    - platform (str): Current platform being processed
    """
    
    def run(self, **kwargs):
        """
        Run the Transform object.
        
        Processes all reference nodes in the document, checking for GitHub
        and GitLab URLs that can be shortened. Only modifies links where
        the display text equals the URL.
        
        Parameters:
        - **kwargs: Additional arguments (unused)
        """
    
    def parse_url(self, uri: ParseResult) -> str:
        """
        Parse the content of the url with respect to the selected platform.
        
        Converts full repository URLs to shortened formats based on the
        platform (GitHub or GitLab) and the type of content being linked.
        
        Parameters:
        - uri (ParseResult): Parsed URL components
        
        Returns:
        str: Shortened, formatted URL text
        """

https://github.com/pydata/pydata-sphinx-theme
→ pydata/pydata-sphinx-theme

https://github.com/pydata/pydata-sphinx-theme/issues/123
→ pydata/pydata-sphinx-theme#123

https://github.com/pydata/pydata-sphinx-theme/pull/456
→ pydata/pydata-sphinx-theme#456

https://github.com/pydata/pydata-sphinx-theme/discussions/789
→ pydata/pydata-sphinx-theme#789

https://github.com/orgs/pydata/projects/5
→ pydata/projects#5

https://gitlab.com/group/subgroup/project
→ group/subgroup/project

https://gitlab.com/group/project/-/issues/123
→ group/project#123

https://gitlab.com/group/project/-/merge_requests/456
→ group/project!456

https://gitlab.com/group/subgroup1/subgroup2/project/-/issues/789
→ group/subgroup1/subgroup2/project#789

See the issue at https://github.com/pydata/pydata-sphinx-theme/issues/123 for details.

Check out this merge request: https://gitlab.com/mygroup/myproject/-/merge_requests/45

<a class="reference external github" href="https://github.com/pydata/pydata-sphinx-theme/issues/123">
    pydata/pydata-sphinx-theme#123
</a>

<a class="reference external gitlab" href="https://gitlab.com/mygroup/myproject/-/merge_requests/45">
    mygroup/myproject!45  
</a>

`Custom link text <https://github.com/pydata/pydata-sphinx-theme/issues/123>`_

<a class="reference external" href="https://github.com/pydata/pydata-sphinx-theme/issues/123">
    Custom link text
</a>

Links to different platforms:

- https://github.com/user/repo → github class added
- https://gitlab.com/user/repo → gitlab class added  
- https://bitbucket.org/user/repo → no processing (not supported)

/* Example custom styling */
a.github {
    color: #24292f;
    font-weight: 500;
}

a.github::before {
    content: "🐙 ";
}

a.gitlab {
    color: #fc6d26;
    font-weight: 500; 
}

a.gitlab::before {
    content: "🦊 ";
}

/* Dark theme variants */
html[data-theme="dark"] a.github {
    color: #f0f6fc;
}

html[data-theme="dark"] a.gitlab {
    color: #fca326;
}

# Custom extension (hypothetical)
from pydata_sphinx_theme.short_link import ShortenLinkTransform

class CustomShortenLinkTransform(ShortenLinkTransform):
    supported_platform = {
        "github.com": "github",
        "gitlab.com": "gitlab", 
        "bitbucket.org": "bitbucket",  # Add Bitbucket support
        "codeberg.org": "codeberg",    # Add Codeberg support
    }
    
    def parse_url(self, uri):
        if self.platform == "bitbucket":
            # Custom Bitbucket parsing logic
            pass
        elif self.platform == "codeberg": 
            # Custom Codeberg parsing logic
            pass
        else:
            return super().parse_url(uri)

# conf.py - Remove the transform (advanced)
def setup(app):
    # Remove the post-transform if already added
    transforms = app.registry.get_post_transforms()
    # Custom logic to remove ShortenLinkTransform
    pass

# conf.py
extlinks = {
    'gh': ('https://github.com/%s', 'GitHub: %s'),
    'gl': ('https://gitlab.com/%s', 'GitLab: %s'),
}

Use :gh:`pydata/pydata-sphinx-theme/issues/123` for short links.

Or use the full URL https://github.com/pydata/pydata-sphinx-theme/issues/123 for automatic processing.

# conf.py
extensions = [
    'sphinx.ext.linkcheck',
    # other extensions
]

# Link checking works normally with shortened links
linkcheck_ignore = [
    r'https://github\.com/.*/issues/\d+',  # Skip checking GitHub issues
]