support in-page anchors in locations

3 files changed, 19 insertions, 1 deletions

diff --git a/src/Formats/HtmlFormatService.kt b/src/Formats/HtmlFormatService.kt
index 733425d7..d5331422 100644
--- a/src/Formats/HtmlFormatService.kt
+++ b/src/Formats/HtmlFormatService.kt
@@ -50,6 +50,10 @@ public open class HtmlFormatService(locationService: LocationService,
         to.appendln("<br/>")
     }
 
+    override fun appendAnchor(to: StringBuilder, anchor: String) {
+        to.appendln("<a name=\"${anchor.htmlEscape()}\"></a>")
+    }
+
     override fun appendTable(to: StringBuilder, body: () -> Unit) {
         to.appendln("<table>")
         body()
diff --git a/src/Formats/MarkdownFormatService.kt b/src/Formats/MarkdownFormatService.kt
index 281ca21d..2bd12c53 100644
--- a/src/Formats/MarkdownFormatService.kt
+++ b/src/Formats/MarkdownFormatService.kt
@@ -59,6 +59,10 @@ public open class MarkdownFormatService(locationService: LocationService,
         to.appendln(text)
     }
 
+    override fun appendAnchor(to: StringBuilder, anchor: String) {
+        // no anchors in Markdown
+    }
+
     override public fun appendParagraph(to: StringBuilder, text: String) {
         to.appendln()
         to.appendln(text)
diff --git a/src/Formats/StructuredFormatService.kt b/src/Formats/StructuredFormatService.kt
index 14eb490a..d2e2436b 100644
--- a/src/Formats/StructuredFormatService.kt
+++ b/src/Formats/StructuredFormatService.kt
@@ -16,6 +16,7 @@ public abstract class StructuredFormatService(locationService: LocationService,
     abstract public fun appendParagraph(to: StringBuilder, text: String)
     abstract public fun appendLine(to: StringBuilder, text: String)
     public abstract fun appendLine(to: StringBuilder)
+    public abstract fun appendAnchor(to: StringBuilder, anchor: String)
 
     public abstract fun appendTable(to: StringBuilder, body: () -> Unit)
     public abstract fun appendTableHeader(to: StringBuilder, body: () -> Unit)
@@ -56,7 +57,7 @@ public abstract class StructuredFormatService(locationService: LocationService,
                 is ContentListItem -> append(formatListItem(formatText(location, content.children)))
 
                 is ContentNodeLink -> {
-                    val linkTo = location.relativePathTo(locationService.location(content.node))
+                    val linkTo = locationHref(location, content.node)
                     val linkText = formatText(location, content.children)
                     append(formatLink(linkText, linkTo))
                 }
@@ -81,6 +82,14 @@ public abstract class StructuredFormatService(locationService: LocationService,
         return FormatLink(to.name, locationService.relativePathToLocation(from, to))
     }
 
+    fun locationHref(from: Location, to: DocumentationNode): String {
+        val topLevelPage = to.references(DocumentationReference.Kind.TopLevelPage).singleOrNull()?.to
+        if (topLevelPage != null) {
+            return from.relativePathTo(locationService.location(topLevelPage), to.name)
+        }
+        return from.relativePathTo(locationService.location(to))
+    }
+
     fun appendDocumentation(location: Location, to: StringBuilder, overloads: Iterable<DocumentationNode>) {
         val breakdownBySummary = overloads.groupByTo(LinkedHashMap()) { node -> node.content }
 
@@ -124,6 +133,7 @@ public abstract class StructuredFormatService(locationService: LocationService,
         subjectSections.forEach {
             val subjectName = it.subjectName
             if (subjectName != null) {
+                appendAnchor(to, subjectName)
                 to.append(formatCode(subjectName)).append(" - ")
                 to.append(formatText(location, it))
                 appendLine(to)