From 13f5a732794e9a25ba08470b2c030b2644e83cde Mon Sep 17 00:00:00 2001
From: Michael Goerz <mail@michaelgoerz.net>
Date: Sun, 5 Mar 2023 13:25:06 -0500
Subject: [PATCH] Add support for `[text](@cite key)` syntax

Closes #63
---
 docs/src/index.md          |  2 ++
 src/DocumenterCitations.jl |  4 +++-
 src/citations.jl           | 19 +++++++++++++++----
 3 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/docs/src/index.md b/docs/src/index.md
index fb0a65b..43fc626 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -43,6 +43,8 @@ Here I cite `Mayer2012`, a useful article, via `[Mayer2012](@cite)`: [Mayer2012]
 
 I also cite `useful_proof`, a book you might not want to read, with `[useful_proof](@cite)` [useful_proof](@cite).
 
+Use e.g. `[arbitrary text](@cite Mayer2012)` to cite a reference with an [arbitrary text](@cite Mayer2012).
+
 Some TeX diacritical marks are supported, e.g. [Heun1900](@cite).
 
 Clicking on the citations takes you to the bibliography.
diff --git a/src/DocumenterCitations.jl b/src/DocumenterCitations.jl
index 4664285..aee360d 100644
--- a/src/DocumenterCitations.jl
+++ b/src/DocumenterCitations.jl
@@ -33,7 +33,9 @@ end
 
 Foo.
 
-[Mayer2012](@cite)
+# Reference
+
+* [Mayer, Krechetnikov, Phys. Rev. E 85, 046117 (2012)](@cite Mayer2012)
 """
 struct Example end
 
diff --git a/src/citations.jl b/src/citations.jl
index 5ecbb94..9fa42ae 100644
--- a/src/citations.jl
+++ b/src/citations.jl
@@ -24,10 +24,17 @@ function expand_citation(elem, page, doc)
 end
 
 function expand_citation(link::Markdown.Link, meta, page, doc)
-    link.url !== "@cite" && return false
-
+    occursin("@cite", link.url) || return false
     if length(link.text) === 1 && isa(link.text[1], String)
-        citation_name = link.text[1]
+        if link.url == "@cite"   # citation format: [key](@cite)
+            citation_name = link.text[1]
+        else  # citation format:                    [text](@cite key)
+            if (m = match(r"^@cite\s*([^\s},]+)\s*$", link.url)) ≢ nothing
+                citation_name = m[1]
+            else
+                error("Invalid citation: [$(link.text)]($(link.url))")
+            end
+        end
         @info "Expanding citation: $citation_name."
 
         if haskey(doc.plugins[CitationBibliography].bib, citation_name)
@@ -39,7 +46,11 @@ function expand_citation(link::Markdown.Link, meta, page, doc)
                     anchor   = Anchors.anchor(headers, entry.id)
                     path     = relpath(anchor.file, dirname(page.build))
                     authors = xnames(entry) |> tex2unicode
-                    link.text = authors * " (" * xyear(entry) * ")"
+                    if link.url == "@cite"
+                        link.text = authors * " (" * xyear(entry) * ")"
+                    else
+                        # keep original link.text
+                    end
                     link.url = string(path, Anchors.fragment(anchor))
                     return true
                 else