Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Omit the number for the first link fragment on a page #1292

Merged
merged 1 commit into from
Apr 16, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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