aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/markup.rst15
-rw-r--r--haddock-api/src/Haddock/Backends/Xhtml.hs8
-rw-r--r--html-test/ref/SectionLabels.html91
-rw-r--r--html-test/src/SectionLabels.hs8
4 files changed, 121 insertions, 1 deletions
diff --git a/doc/markup.rst b/doc/markup.rst
index 08510804..af71e7c7 100644
--- a/doc/markup.rst
+++ b/doc/markup.rst
@@ -508,6 +508,19 @@ on, where the number of ``*``\ s indicates the level of the heading
If you use section headings, then Haddock will generate a table of
contents at the top of the module documentation for you.
+By default, when generating HTML documentation Haddock will create an
+anchor to each section of the form ``#g:n``, where ``n`` is an integer
+that might change as you add new section headings. If you want to
+create stable links, you can add an explicit anchor (see
+:ref:`anchors`) after the section heading: ::
+
+ module Foo (
+ -- * Classes #classes#
+ C(..)
+ ) where
+
+This will create an HTML anchor ``#g:classes`` to the section.
+
The alternative style of placing the commas at the beginning of each
line is also supported. e.g.: ::
@@ -1150,6 +1163,8 @@ Inspired by reSTs grid tables Haddock supports a complete table representation v
-- | body row 4 | | \] |
-- +------------------------+------------+---------------------+
+.. _anchors:
+
Anchors
~~~~~~~
diff --git a/haddock-api/src/Haddock/Backends/Xhtml.hs b/haddock-api/src/Haddock/Backends/Xhtml.hs
index e3d4e8ca..4e87d0be 100644
--- a/haddock-api/src/Haddock/Backends/Xhtml.hs
+++ b/haddock-api/src/Haddock/Backends/Xhtml.hs
@@ -672,10 +672,16 @@ numberSectionHeadings = go 1
where go :: Int -> [ExportItem DocNameI] -> [ExportItem DocNameI]
go _ [] = []
go n (ExportGroup lev _ doc : es)
- = ExportGroup lev (show n) doc : go (n+1) es
+ = case collectAnchors doc of
+ [] -> ExportGroup lev (show n) doc : go (n+1) es
+ (a:_) -> ExportGroup lev a doc : go (n+1) es
go n (other:es)
= other : go n es
+ collectAnchors :: DocH (Wrap (ModuleName, OccName)) (Wrap DocName) -> [String]
+ collectAnchors (DocAppend a b) = collectAnchors a ++ collectAnchors b
+ collectAnchors (DocAName a) = [a]
+ collectAnchors _ = []
processExport :: Bool -> LinksInfo -> Bool -> Maybe Package -> Qualification
-> ExportItem DocNameI -> Maybe Html
diff --git a/html-test/ref/SectionLabels.html b/html-test/ref/SectionLabels.html
new file mode 100644
index 00000000..4581082e
--- /dev/null
+++ b/html-test/ref/SectionLabels.html
@@ -0,0 +1,91 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml"
+><head
+ ><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"
+ /><meta name="viewport" content="width=device-width, initial-scale=1"
+ /><title
+ >SectionLabels</title
+ ><link href="#" rel="stylesheet" type="text/css" title="Linuwial"
+ /><link rel="stylesheet" type="text/css" href="#"
+ /><link rel="stylesheet" type="text/css" href="#"
+ /><script src="haddock-bundle.min.js" async="async" type="text/javascript"
+ ></script
+ ><script type="text/x-mathjax-config"
+ >MathJax.Hub.Config({ tex2jax: { processClass: "mathjax", ignoreClass: ".*" } });</script
+ ><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"
+ ></script
+ ></head
+ ><body
+ ><div id="package-header"
+ ><span class="caption empty"
+ >&nbsp;</span
+ ><ul class="links" id="page-menu"
+ ><li
+ ><a href="#"
+ >Contents</a
+ ></li
+ ><li
+ ><a href="#"
+ >Index</a
+ ></li
+ ></ul
+ ></div
+ ><div id="content"
+ ><div id="module-header"
+ ><table class="info"
+ ><tr
+ ><th
+ >Safe Haskell</th
+ ><td
+ >Safe-Inferred</td
+ ></tr
+ ></table
+ ><p class="caption"
+ >SectionLabels</p
+ ></div
+ ><div id="table-of-contents"
+ ><div id="contents-list"
+ ><p class="caption" onclick="window.scrollTo(0,0)"
+ >Contents</p
+ ><ul
+ ><li
+ ><a href="#"
+ >Section heading</a
+ ></li
+ ></ul
+ ></div
+ ></div
+ ><div id="synopsis"
+ ><details id="syn"
+ ><summary
+ >Synopsis</summary
+ ><ul class="details-toggle" data-details-id="syn"
+ ><li class="src short"
+ ><a href="#"
+ >n</a
+ > :: <a href="#" title="Data.Int"
+ >Int</a
+ ></li
+ ></ul
+ ></details
+ ></div
+ ><div id="interface"
+ ><a href="#" id="g:custom"
+ ><h1
+ >Section heading</h1
+ ></a
+ ><div class="top"
+ ><p class="src"
+ ><a id="v:n" class="def"
+ >n</a
+ > :: <a href="#" title="Data.Int"
+ >Int</a
+ > <a href="#" class="selflink"
+ >#</a
+ ></p
+ ></div
+ ></div
+ ></div
+ ></body
+ ></html
+>
diff --git a/html-test/src/SectionLabels.hs b/html-test/src/SectionLabels.hs
new file mode 100644
index 00000000..560bafa4
--- /dev/null
+++ b/html-test/src/SectionLabels.hs
@@ -0,0 +1,8 @@
+module SectionLabels
+ (
+ -- * Section heading#custom#
+ n
+ ) where
+
+n :: Int
+n = 3