ENH: Add GitHub Projects support for github shorten links (#1051)

* Add project support to github shorten links

* Use PyData project

* Remove deflist

docs/conf.py

@@ -60,7 +60,7 @@
 # -- Extension options -------------------------------------------------------
 
 # This allows us to use ::: to denote directives, useful for admonitions
-myst_enable_extensions = ["colon_fence", "substitution"]
+myst_enable_extensions = ["colon_fence", "linkify", "substitution"]
 
 # -- Options for HTML output -------------------------------------------------
 

docs/user_guide/theme-elements.md

@@ -164,20 +164,45 @@ Some sidebar content.
 
 ## Link shortening for git repository services
 
-Many projects have links back to their issues / PRs hosted on platforms like **GitHub** or **GitLab**. Instead of displaying these as raw links, this theme does some lightweight formatting for these platforms specifically. Here is some examples from github and gitlab:
+Many projects have links back to their issues / PRs hosted on platforms like **GitHub** or **GitLab**.
+Instead of displaying these as raw links, this theme does some lightweight formatting for these platforms specifically.
+
+In **reStructuredText**, URLs are automatically converted to links, so this works automatically.
+
+In **MyST Markdown**, by default you must define a standard markdown link and duplicate the URL in the link text.
+You may skip the need to manually define the link text by [activating the MyST Linkify extension](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#linkify).
+
+For example:
+
+- **reStructuredText**
+
+  - `https://github.com/pydata/pydata-sphinx-theme/pull/1012`
+  - https://github.com/pydata/pydata-sphinx-theme/pull/1012
+
+- **MyST Markdown (default)**
+
+  - `[https://github.com/pydata/pydata-sphinx-theme/pull/1012](https://github.com/pydata/pydata-sphinx-theme/pull/1012)`
+  - [https://github.com/pydata/pydata-sphinx-theme/pull/1012](https://github.com/pydata/pydata-sphinx-theme/pull/1012)
+
+- **MyST Markdown with [MyST Linkify](https://myst-**parser.readthedocs.io/en/latest/syntax/optional.html#linkify)
+  - `https://github.com/pydata/pydata-sphinx-theme/pull/1012`
+  - https://github.com/pydata/pydata-sphinx-theme/pull/1012
+
+There are a variety of link targets supported, here's a table for reference:
 
 **GitHub**
 
-- "https://github.com" -> [https://github.com](https://github.com)
-- "https://github.com/pydata" -> [https://github.com/pydata](https://github.com/pydata)
-- "https://github.com/pydata/pydata-sphinx-theme" -> [https://github.com/pydata/pydata-sphinx-theme](https://github.com/pydata/pydata-sphinx-theme)
-- "https://github.com/pydata/pydata-sphinx-theme/pull/1012" -> [https://github.com/pydata/pydata-sphinx-theme/pull/1012](https://github.com/pydata/pydata-sphinx-theme/pull/1012)
+- `https://github.com`: https://github.com
+- `https://github.com/pydata`: https://github.com/pydata
+- `https://github.com/pydata/pydata-sphinx-theme`: https://github.com/pydata/pydata-sphinx-theme
+- `https://github.com/pydata/pydata-sphinx-theme/pull/1012`: https://github.com/pydata/pydata-sphinx-theme/pull/1012
+- `https://github.com/orgs/pydata/projects/2`: https://github.com/orgs/pydata/projects/2
 
 **GitLab**
 
-- "https://gitlab.com" -> [https://gitlab.com](https://gitlab.com)
-- "https://gitlab.com/gitlab-org" -> [https://gitlab.com/gitlab-org](https://gitlab.com/gitlab-org)
-- "https://gitlab.com/gitlab-org/gitlab" -> [https://gitlab.com/gitlab-org/gitlab](https://gitlab.com/gitlab-org/gitlab)
-- "https://gitlab.com/gitlab-org/gitlab/-/issues/375583" -> [https://gitlab.com/gitlab-org/gitlab/-/issues/375583](https://gitlab.com/gitlab-org/gitlab/-/issues/375583)
+- `https://gitlab.com`: https://gitlab.com
+- `https://gitlab.com/gitlab-org`: https://gitlab.com/gitlab-org
+- `https://gitlab.com/gitlab-org/gitlab`: https://gitlab.com/gitlab-org/gitlab
+- `https://gitlab.com/gitlab-org/gitlab/-/issues/375583`: https://gitlab.com/gitlab-org/gitlab/-/issues/375583
 
 Links provided with a text body won't be changed.

pyproject.toml

@@ -45,6 +45,7 @@ classifiers = [
 doc = [
   "numpydoc",
   "myst-nb",
+  "linkify-it-py",  # for link shortening
   "pytest",
   "pytest-regressions",
   "rich",

src/pydata_sphinx_theme/__init__.py

@@ -947,13 +947,20 @@ def parse_url(self, uri):
         if self.platform == "github":
             # split the url content
             parts = path.split("/")
-            if len(parts) > 0:
-                text = parts[0]  # organisation
-            if len(parts) > 1:
-                text += f"/{parts[1]}"  # repository
-            if len(parts) > 2:
-                if parts[2] in ["issues", "pull", "discussions"]:
-                    text += f"#{parts[-1]}"  # element number
+
+            if parts[0] == "orgs" and "/projects" in path:
+                # We have a projects board link
+                # ref: `orgs/{org}/projects/{project-id}`
+                text = f"{parts[1]}/projects#{parts[3]}"
+            else:
+                # We have an issues, PRs, or repository link
+                if len(parts) > 0:
+                    text = parts[0]  # organisation
+                if len(parts) > 1:
+                    text += f"/{parts[1]}"  # repository
+                if len(parts) > 2:
+                    if parts[2] in ["issues", "pull", "discussions"]:
+                        text += f"#{parts[-1]}"  # element number
 
         elif self.platform == "gitlab":
             # cp. https://docs.gitlab.com/ee/user/markdown.html#gitlab-specific-references

tests/sites/base/page1.rst

@@ -13,6 +13,7 @@ Page 1
     https://github.com/pydata
     https://github.com/pydata/pydata-sphinx-theme
     https://github.com/pydata/pydata-sphinx-theme/pull/1012
+    https://github.com/orgs/pydata/projects/2
 
 **GitLab**
 

tests/test_build/github_links.html

@@ -12,5 +12,8 @@
   <a class="github reference external" href="https://github.com/pydata/pydata-sphinx-theme/pull/1012">
    pydata/pydata-sphinx-theme#1012
   </a>
+  <a class="github reference external" href="https://github.com/orgs/pydata/projects/2">
+   pydata/projects#2
+  </a>
  </p>
 </div>