Add support for [text](@cite key) syntax

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.

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
 

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