From 142bbeefa57601bf6f2d6f2acc0ef3a47f80a534 Mon Sep 17 00:00:00 2001
From: nathan musoke <nathan.musoke@gmail.com>
Date: Tue, 16 Apr 2024 18:51:50 -0400
Subject: [PATCH] Remove at-extref from non-Documenter output (#245)

---
 CHANGELOG.md           | 10 ++++++++++
 docs/src/documenter.md |  8 ++++----
 src/Literate.jl        |  4 +++-
 test/runtests.jl       |  6 +++++-
 4 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1a106577..b5d342ef 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+ - Literate will now remove Documenter-style `@extref` links under the same
+   circumstances as `@ref` and `@id`.  Recent versions of Documenter use
+   `@extref` to links to the documentation of external packages.  See
+   https://github.com/JuliaDocs/Documenter.jl/issues/2366 for details of
+   the Documenter implementation. ([#245])
+
 ## [v2.17.0] - 2024-04-14
 ### Added
  - Literate can now output [Quarto](https://quarto.org/) notebooks (markdown documents with
@@ -303,6 +312,7 @@ https://discourse.julialang.org/t/ann-literate-jl/10651 for release announcement
 [#229]: https://github.com/fredrikekre/Literate.jl/issues/229
 [#230]: https://github.com/fredrikekre/Literate.jl/issues/230
 [#233]: https://github.com/fredrikekre/Literate.jl/issues/233
+[#245]: https://github.com/fredrikekre/Literate.jl/issues/245
 [0872a96]: https://github.com/fredrikekre/Literate.jl/commit/0872a96
 [0f9e836]: https://github.com/fredrikekre/Literate.jl/commit/0f9e836
 [1d02868]: https://github.com/fredrikekre/Literate.jl/commit/1d02868
diff --git a/docs/src/documenter.md b/docs/src/documenter.md
index 72057b95..55984239 100644
--- a/docs/src/documenter.md
+++ b/docs/src/documenter.md
@@ -31,8 +31,8 @@ if we set `documenter = true`:
   ````
 
 ### [`Literate.notebook`](@ref):
-- Documenter style `@ref`s and `@id` will be removed. This means that you can use
-  `@ref` and `@id` in the source file without them leaking to the notebook.
+- Documenter style `@ref`s, `@extref`s and `@id` will be removed. This means that you can use
+  `@ref`, `@extref` and `@id` in the source file without them leaking to the notebook.
 - Documenter style markdown math
   ````
   ```math
@@ -57,5 +57,5 @@ if we set `documenter = true`:
   ```
 
 ### [`Literate.script`](@ref):
-- Documenter style `@ref`s and `@id` will be removed. This means that you can use
-  `@ref` and `@id` in the source file without them leaking to the script.
+- Documenter style `@ref`s, `@extref`s and `@id` will be removed. This means that you can use
+  `@ref`, `@extref` and `@id` in the source file without them leaking to the script.
diff --git a/src/Literate.jl b/src/Literate.jl
index 55a064f1..046bd87e 100644
--- a/src/Literate.jl
+++ b/src/Literate.jl
@@ -217,9 +217,11 @@ function replace_default(content, sym;
 
     # Run some Documenter specific things
     if !isdocumenter(config)
-        ## - remove documenter style `@ref`s and `@id`s
+        ## - remove documenter style `@ref`s, `@extref`s and `@id`s
         push!(repls, r"\[([^]]+?)\]\(@ref\)"s => s"\1")     # [foo](@ref) => foo
         push!(repls, r"\[([^]]+?)\]\(@ref .*?\)"s => s"\1") # [foo](@ref bar) => foo
+        push!(repls, r"\[([^]]+?)\]\(@extref\)"s => s"\1")     # [foo](@extref) => foo
+        push!(repls, r"\[([^]]+?)\]\(@extref .*?\)"s => s"\1") # [foo](@extref bar) => foo
         push!(repls, r"\[([^]]+?)\]\(@id .*?\)"s => s"\1")  # [foo](@id bar) => foo
     end
 
diff --git a/test/runtests.jl b/test/runtests.jl
index ba6ca3d6..ee1e221d 100644
--- a/test/runtests.jl
+++ b/test/runtests.jl
@@ -220,6 +220,7 @@ end # testset parser
 content = """
     # # [Example](@id example-id)
     # [foo](@ref), [bar](@ref bbaarr)
+    # [baz](@extref), [bax](@extref bbaaxx)
     x = 1
     #md # Only markdown
     # Only markdown #md
@@ -580,6 +581,7 @@ end end
 
             # [Example](@id example-id)
             [foo](@ref), [bar](@ref bbaarr)
+            [baz](@extref), [bax](@extref bbaaxx)
 
             ````@example inputfile
             x = 1
@@ -1027,7 +1029,8 @@ end end
             """
                "source": [
                 "# Example\\n",
-                "foo, bar"
+                "foo, bar\\n",
+                "baz, bax"
                ]
             """,
 
@@ -1263,6 +1266,7 @@ end end
             notebook = read(joinpath(outdir, "inputfile.ipynb"), String)
             @test !occursin("# [Example](@id example-id", notebook)
             @test !occursin("[foo](@ref), [bar](@ref bbaarr)", notebook)
+            @test !occursin("[baz](@ref), [bax](@ref bbaaxx)", notebook)
 
             # name
             Literate.notebook(inputfile, outdir, name = "foobar", execute = false)