Skip to content

Commit

Permalink
Omit the number for the first link fragment on a page;
Browse files Browse the repository at this point in the history
Before: #foobar-1, #foobar-2,
After: #foobar, #foobar-2.

For legacy reasons the old fragments are also insert in
order to not break old links spread throughout the internet.
  • Loading branch information
fredrikekre committed Apr 16, 2020
1 parent 048d2fa commit cc56dec
Show file tree
Hide file tree
Showing 5 changed files with 38 additions and 16 deletions.
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@

* ![Bugfix][badge-bugfix] `Deps.pip` is again a closure and gets executed during the `deploydocs` call, not before it. ([#1240][github-1240])

* ![Enhancement][badge-enhancement] The first link fragment on each page now omits the number; before the rendering resulted in: `#foobar-1`, `#foobar-2`, and now: `#foobar`, `#foobar-2`. For backwards compatibility the old fragments are also inserted such that old links will still point to the same location. ([#1292][github-1292])

## Version `v0.24.9`

* ![Bugfix][badge-bugfix] Canonical URLs are now properly prettified (e.g. `/path/` instead of `/path/index.html`) when using `prettyurls=true`. ([#1293][github-1293])
Expand Down Expand Up @@ -544,6 +546,7 @@
[github-1269]: https://github.com/JuliaDocs/Documenter.jl/pull/1269
[github-1279]: https://github.com/JuliaDocs/Documenter.jl/issues/1279
[github-1280]: https://github.com/JuliaDocs/Documenter.jl/pull/1280
[github-1292]: https://github.com/JuliaDocs/Documenter.jl/pull/1292
[github-1293]: https://github.com/JuliaDocs/Documenter.jl/pull/1293

[documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl
Expand Down
13 changes: 13 additions & 0 deletions src/Anchors.jl
Original file line number Diff line number Diff line change
Expand Up @@ -124,4 +124,17 @@ function anchor(m::AnchorMap, id, file, n)
nothing
end

"""
Create an HTML fragment from an anchor.
"""
function fragment(a::Anchor)
frag = string("#", a.id)
if a.nth > 1
frag = string(frag, "-", a.nth)
end
# TODO: Sanitize the fragment
return frag
end


end
2 changes: 1 addition & 1 deletion src/CrossReferences.jl
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ function namedxref(link::Markdown.Link, slug, meta, page, doc)
# Replace the `@ref` url with a path to the referenced header.
anchor = Anchors.anchor(headers, slug)
path = relpath(anchor.file, dirname(page.build))
link.url = string(path, '#', slug, '-', anchor.nth)
link.url = string(path, Anchors.fragment(anchor))
else
push!(doc.internal.errors, :cross_references)
@warn "'$slug' is not unique in $(Utilities.locrepr(page.source))."
Expand Down
28 changes: 15 additions & 13 deletions src/Writers/HTMLWriter.jl
Original file line number Diff line number Diff line change
Expand Up @@ -470,7 +470,7 @@ end
struct SearchRecord
src :: String
page :: Documents.Page
loc :: String
fragment :: String
category :: String
title :: String
page_title :: String
Expand All @@ -496,15 +496,15 @@ end

HTMLContext(doc, settings=HTML()) = HTMLContext(doc, settings, [], "", "", "", [], "", Documents.NavNode("search", "Search", nothing), [])

function SearchRecord(ctx::HTMLContext, navnode; loc="", title=nothing, category="page", text="")
function SearchRecord(ctx::HTMLContext, navnode; fragment="", title=nothing, category="page", text="")
page_title = mdflatten(pagetitle(ctx, navnode))
if title === nothing
title = page_title
end
SearchRecord(
pretty_url(ctx, get_url(ctx, navnode.page)),
getpage(ctx, navnode),
loc,
fragment,
lowercase(category),
title,
page_title,
Expand All @@ -515,7 +515,7 @@ end
function SearchRecord(ctx::HTMLContext, navnode, node::Markdown.Header)
a = getpage(ctx, navnode).mapping[node]
SearchRecord(ctx, navnode;
loc="$(a.id)-$(a.nth)",
fragment=Anchors.fragment(a),
title=mdflatten(node),
category="section")
end
Expand All @@ -527,7 +527,7 @@ end
function JSON.lower(rec::SearchRecord)
# Replace any backslashes in links, if building the docs on Windows
src = replace(rec.src, '\\' => '/')
ref = string(src, '#', rec.loc)
ref = string(src, rec.fragment)
Dict{String, String}(
"location" => ref,
"page" => rec.page_title,
Expand Down Expand Up @@ -1218,16 +1218,18 @@ end

function domify(ctx, navnode, anchor::Anchors.Anchor)
@tags a
aid = "$(anchor.id)-$(anchor.nth)"
frag = Anchors.fragment(anchor)
legacy = anchor.nth == 1 ? (a[:id => lstrip(frag, '#')*"-1"],) : ()
if isa(anchor.object, Markdown.Header)
h = anchor.object
fixlinks!(ctx, navnode, h)
DOM.Tag(Symbol("h$(Utilities.header_level(h))"))[:id => aid](
a[".docs-heading-anchor", :href => "#$aid"](mdconvert(h.text, h)),
a[".docs-heading-anchor-permalink", :href => "#$aid", :title => "Permalink"]
DOM.Tag(Symbol("h$(Utilities.header_level(h))"))[:id => lstrip(frag, '#')](
a[".docs-heading-anchor", :href => frag](mdconvert(h.text, h)),
legacy...,
a[".docs-heading-anchor-permalink", :href => frag, :title => "Permalink"]
)
else
a[:id => aid, :href => "#$aid"](domify(ctx, navnode, anchor.object))
a[:id => frag, :href => frag](legacy..., domify(ctx, navnode, anchor.object))
end
end

Expand Down Expand Up @@ -1264,7 +1266,7 @@ function domify(ctx, navnode, contents::Documents.ContentsNode)
path = joinpath(navnode_dir, path) # links in ContentsNodes are relative to current page
path = pretty_url(ctx, relhref(navnode_url, get_url(ctx, path)))
header = anchor.object
url = string(path, '#', anchor.id, '-', anchor.nth)
url = string(path, Anchors.fragment(anchor))
node = a[:href=>url](mdconvert(header.text; droplinks=true))
level = Utilities.header_level(header)
push!(lb, level, node)
Expand Down Expand Up @@ -1295,7 +1297,7 @@ function domify(ctx, navnode, node::Documents.DocsNode)

# push to search index
rec = SearchRecord(ctx, navnode;
loc=node.anchor.id,
fragment=Anchors.fragment(node.anchor),
title=string(node.object.binding),
category=Utilities.doccat(node.object),
text = mdflatten(node.docstr))
Expand Down Expand Up @@ -1469,7 +1471,7 @@ function collect_subsections(page::Documents.Page)
continue
end
anchor = page.mapping[element]
push!(sections, (toplevel, "#$(anchor.id)-$(anchor.nth)", element.text))
push!(sections, (toplevel, Anchors.fragment(anchor), element.text))
end
end
return sections
Expand Down
8 changes: 6 additions & 2 deletions src/Writers/MarkdownWriter.jl
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,11 @@ function render(io::IO, mime::MIME"text/plain", vec::Vector, page, doc)
end

function render(io::IO, mime::MIME"text/plain", anchor::Anchors.Anchor, page, doc)
println(io, "\n<a id='", anchor.id, "-", anchor.nth, "'></a>")
println(io, "\n<a id='", lstrip(Anchors.fragment(anchor), '#'), "'></a>")
if anchor.nth == 1 # add legacy id
legacy = lstrip(Anchors.fragment(anchor), '#') * "-1"
println(io, "\n<a id='", legacy, "'></a>")
end
render(io, mime, anchor.object, page, doc)
end

Expand Down Expand Up @@ -125,7 +129,7 @@ function render(io::IO, ::MIME"text/plain", contents::Documents.ContentsNode, pa
for (count, path, anchor) in contents.elements
path = mdext(path)
header = anchor.object
url = string(path, '#', anchor.id, '-', anchor.nth)
url = string(path, Anchors.fragment(anchor))
link = MarkdownStdlib.Link(header.text, url)
level = Utilities.header_level(header)
print(io, " "^(level - 1), "- ")
Expand Down

0 comments on commit cc56dec

Please sign in to comment.