3 files changed, 160 insertions, 3 deletions
diff --git a/nimdoc/testproject/subdir/subdir_b/utils.nim b/nimdoc/testproject/subdir/subdir_b/utils.nim
index 128e8e481..f535d7f74 100644
--- a/nimdoc/testproject/subdir/subdir_b/utils.nim
+++ b/nimdoc/testproject/subdir/subdir_b/utils.nim
@@ -1,5 +1,7 @@
 ##[
 
+.. include:: ./utils_overview.rst
+
 # This is now a header
 
 ## Next header
@@ -19,18 +21,70 @@ More text.
 1. Other case value
 2. Second case.
 
+Ref group fn2_ or specific function like `fn2()`_
+or `fn2(  int  )`_ or `fn2(int,
+float)`_.
+
+Ref generics like this: binarySearch_ or `binarySearch(openArray[T], K,
+proc (T, K))`_ or `proc binarySearch(openArray[T], K,  proc (T, K))`_ or
+in different style: `proc binarysearch(openarray[T], K, proc(T, K))`_.
+Can be combined with export symbols and type parameters:
+`binarysearch*[T, K](openArray[T], K, proc (T, K))`_.
+With spaces `binary search`_.
+
+Note that `proc` can be used in postfix form: `binarySearch proc`_.
+
+Ref. type like G_ and `type G`_ and `G[T]`_ and `type G*[T]`_.
+
+Group ref. with capital letters works: fN11_ or fn11_
 ]##
 
+include ./utils_helpers
+
 type
   SomeType* = enum
     enumValueA,
     enumValueB,
     enumValueC
+  G*[T] = object
+    val: T
 
 proc someType*(): SomeType =
   ## constructor.
   SomeType(2)
 
+
+proc fn2*() = discard ## comment
+proc fn2*(x: int) =
+  ## fn2 comment
+  discard
+proc fn2*(x: int, y: float) =
+  discard
+proc binarySearch*[T, K](a: openArray[T]; key: K;
+                         cmp: proc (x: T; y: K): int {.closure.}): int =
+  discard
+proc fn3*(): auto = 1 ## comment
+proc fn4*(): auto = 2 * 3 + 4 ## comment
+proc fn5*() ## comment
+proc fn5*() = discard
+proc fn6*() =
+  ## comment
+proc fn7*() =
+  ## comment
+  discard
+proc fn8*(): auto =
+  ## comment
+  1+1
+func fn9*(a: int): int = 42  ## comment
+func fn10*(a: int): int = a  ## comment
+
+# Note capital letter N will be handled correctly in
+# group references like fN11_ or fn11_
+# (or [fN11] or [fn11] in Markdown Syntax):
+
+func fN11*() = discard
+func fN11*(x: int) = discard
+
 # bug #9235
 
 template aEnum*(): untyped =
@@ -50,9 +104,9 @@ template bEnum*(): untyped =
     discard
 
 template fromUtilsGen*(): untyped =
-  ## this should be shown in utils.html
+  ## should be shown in utils.html only
   runnableExamples:
-    assert 3*2 == 6
+    discard "should be in utils.html only, not in module that calls fromUtilsGen"
   ## ditto
 
   iterator fromUtils1*(): int =
@@ -64,7 +118,96 @@ template fromUtilsGen*(): untyped =
 
   template fromUtils2*() =
     ## ok3
+    runnableExamples:
+      discard """should be shown as examples for fromUtils2
+       in module calling fromUtilsGen"""
 
   proc fromUtils3*() =
     ## came form utils but should be shown where `fromUtilsGen` is called
-    runnableExamples: discard 1
+    runnableExamples: discard """should be shown as examples for fromUtils3
+       in module calling fromUtilsGen"""
+
+proc f*(x: G[int]) =
+  ## There is also variant `f(G[string])`_
+  discard
+proc f*(x: G[string]) =
+  ## See also `f(G[int])`_.
+  discard
+
+## Ref. `[]`_ is the same as `proc \`[]\`(G[T])`_ because there are no
+## overloads. The full form: `proc \`[]\`*[T](x: G[T]): T`_
+
+proc `[]`*[T](x: G[T]): T = x.val
+
+## Ref. `[]=`_ aka `\`[]=\`(G[T], int, T)`_.
+
+proc `[]=`*[T](a: var G[T], index: int, value: T) = discard
+
+## Ref. `$`_ aka `proc $`_ or `proc \`$\``_.
+
+proc `$`*[T](a: G[T]): string = ""
+
+## Ref. `$(a: ref SomeType)`_.
+
+proc `$`*[T](a: ref SomeType): string = ""
+
+## Ref. foo_bar_ aka `iterator foo_bar_`_.
+
+iterator fooBar*(a: seq[SomeType]): int = discard
+
+## Ref. `fn[T; U,V: SomeFloat]()`_.
+
+proc fn*[T; U, V: SomeFloat]() = discard
+
+## Ref. `'big`_ or `func \`'big\``_ or `\`'big\`(string)`_.
+
+func `'big`*(a: string): SomeType = discard
+
+##[
+
+Pandoc Markdown
+===============
+
+Now repeat all the auto links of above in Pandoc Markdown Syntax.
+
+Ref group [fn2] or specific function like [fn2()]
+or [fn2(  int  )] or [fn2(int,
+float)].
+
+Ref generics like this: [binarySearch] or [binarySearch(openArray[T], K,
+proc (T, K))] or [proc binarySearch(openArray[T], K,  proc (T, K))] or
+in different style: [proc binarysearch(openarray[T], K, proc(T, K))].
+Can be combined with export symbols and type parameters:
+[binarysearch*[T, K](openArray[T], K, proc (T, K))].
+With spaces [binary search].
+
+Note that `proc` can be used in postfix form: [binarySearch proc].
+
+Ref. type like [G] and [type G] and [G[T]] and [type G*[T]].
+
+Group ref. with capital letters works: [fN11] or [fn11]
+
+Ref. [`[]`] is the same as [proc `[]`(G[T])] because there are no
+overloads. The full form: [proc `[]`*[T](x: G[T]): T]
+Ref. [`[]=`] aka [`[]=`(G[T], int, T)].
+Ref. [$] aka [proc $] or [proc `$`].
+Ref. [$(a: ref SomeType)].
+Ref. [foo_bar] aka [iterator foo_bar_].
+Ref. [fn[T; U,V: SomeFloat]()].
+Ref. ['big] or [func `'big`] or [`'big`(string)].
+
+Link name syntax
+----------------
+
+Pandoc Markdown has synax for changing text of links:
+Ref. [this proc][`[]`] or [another symbol][G[T]].
+
+Symbols documentation
+---------------------
+
+Let us repeat auto links from symbols section below:
+
+There is also variant [f(G[string])].
+See also [f(G[int])].
+
+]##
diff --git a/nimdoc/testproject/subdir/subdir_b/utils_helpers.nim b/nimdoc/testproject/subdir/subdir_b/utils_helpers.nim
new file mode 100644
index 000000000..d3f5edd29
--- /dev/null
+++ b/nimdoc/testproject/subdir/subdir_b/utils_helpers.nim
@@ -0,0 +1,6 @@
+proc funWithGenerics*[T, U: SomeFloat](a: T, b: U) = discard
+
+# We check that presence of overloaded `fn2` here does not break
+# referencing in the "parent" file (the one that includes this one)
+proc fn2*(x: int, y: float, z: float) =
+  discard
diff --git a/nimdoc/testproject/subdir/subdir_b/utils_overview.rst b/nimdoc/testproject/subdir/subdir_b/utils_overview.rst
new file mode 100644
index 000000000..58ce930bf
--- /dev/null
+++ b/nimdoc/testproject/subdir/subdir_b/utils_overview.rst
@@ -0,0 +1,8 @@
+This is a description of the utils module.
+
+Links work:
+
+* other module: `iterators <iterator.html>`_ (not in this dir, just an example)
+* internal: `fn2(x)`_
+* internal included from another module: `funWithGenerics*[T, U:
+  SomeFloat](a: T, b: U)`_.