More Useful Links in "Print entire section" Mode

[boevski]

DL;DR: Need working links in print mode.

Long version:

The idea behind the "Print entire section" feature us great. I was researching it for the purpose of PDF creation where it makes it easy to use whatever PDF converter you like, even automation, in an elegant way. Unfortunately, I found out a pretty major deficiency - it keeps the links unchanged, meaning they point to pages outside the _print page. It doesn't make a difference when printing on paper, but when printing to PDF (which, I guess, is far more common nowadays), it means losing functionality and context. This, with the presence of broken links, makes the resulting PDF completely unfit for professional use like handing over to customers.

What would it take to redo the links so that they work within the context of the monolithic _print page?

I understand this might not be everybody's cup of tea, so it could be a configuration option.
It will require generating ids for headings that don't already have them. For the anchor links, simply dropping the URL part preceding the hash sign won't do, as multiple of the original pages might use the same ids. These will have to be replaced by autogenerated UUIDs or prefixed/suffixed with something to make them unique.

[boevski]

I made some progress towards fixing the links but I hit a wall: The .Site methods are nil in layouts/partials/print/content.html where the code for laying out the _print page resides. Both .Site and $.Site return nil.

Is there a way to access .Site from the content.html template? Is _print treated differently because it is an "in memory" page as opposed to being a part of the file structure?

[boevski]

Ok guys, check this solution I came up with.
It involves creating print-specific render hooks for headings and links.

Put the following code in layouts/_default/_markup/render-heading.print.html

<h{{ .Level }} id="{{ (print .Anchor .Page.File.UniqueID) | safeURL }}"
{{- with .Attributes.class }} class="{{ . }}" {{- end -}}
>
{{- .Text | safeHTML -}}
<a class="td-heading-self-link" href="#{{ (print .Anchor .Page.File.UniqueID) | safeURL }}" aria-label="Heading self-link"></a>
</h{{ .Level }}>

It normally creates self-anchors for all headings. I modified it to append the unique file ID of each file (href="#foobar875935964fc6d1e64cb4d3451cdf0779") to prevent repeating IDs within the _print page in case multiple files contain the same ID.

Put the following code in layouts/_default/_markup/render-link.print.html

{{- $u := urls.Parse .Destination -}}
{{ $linkPageContext := . }}

{{- if $u.IsAbs -}}
  <a href="{{ .Destination | safeURL }}"
    {{- with .Title }} title="{{ . }}"{{ end -}}
    rel="external"
  >
    {{- with .Text }}{{ . }}{{ end -}}
  </a>
{{- else if not $u.Path -}}
  <a href="{{ (print .Destination .Page.File.UniqueID ) | safeURL }}"
    {{- with .Title }} title="{{ . }}" {{ end -}}
  >
    {{- with .Text }}{{ . }}{{ end -}}
  </a>
{{- else -}}
  {{- with .Page.GetPage $u.Path }}
    {{- with $u.Fragment -}}
      <a href="{{ (print "#" . .File.UniqueID) | safeURL }}"
      {{- with $linkPageContext.Title }} title="{{ . }}"{{ end -}}
      >
      {{- with $linkPageContext.Text }}{{ . }}{{ end -}}
      </a>
    {{- else -}}
      <a href="{{ (print "#" .File.UniqueID) | safeURL }}"
      {{- with $linkPageContext.Title }} title="{{ . }}"{{ end -}}
      >
      {{- with $linkPageContext.Text }}{{ . }}{{ end -}}
      </a>
    {{- end -}}
  {{ end -}}
{{ end -}}

• It uses the IsAbs method to recognize external links and leave them unchanged.
• It replaces links that contain a file path only (like docs/overview.html) with the file's unique ID as an ID (href="#28cedb2567cb30e9484048cb10eaac4a"), which is the anchor of H1s created by Docsy (see content.html below).
• It appends links that only contain an anchor (href="#foobar") with the unique ID of the file they are contained in (href="foobar#28cedb2567cb30e9484048cb10eaac4a")

I also ever so slightly changed how the IDs of article titles (H1s) are generated. This is based on my own preference, but since the code above depend on it, you'll also have to redefine layouts/partials/print/content.html. The only change to it is removing the pg- prefix on H1 IDs on line 9 (so instead of id="#pg-875935964fc6d1e64cb4d3451cdf0779" you'll get id="#875935964fc6d1e64cb4d3451cdf0779"):

{{ $tpl := printf "print/content-%s.html" .Page.Type }}

{{ if templates.Exists (printf "partials/%s" $tpl) }}
  {{ partial $tpl . }}
{{ else -}}
{{ $break := cond .DoPageBreak "page-break-before: always" "" -}}
<div class="td-content" style="{{ $break }}">
    {{ $break := cond .DoPageBreak "page-break-before: always" "" }}
	<h1 id="{{ .Page.File.UniqueID }}">{{ .PageNum }}. {{ .Page.Title }}</h1>
    {{ with .Page.Params.description }}<div class="lead">{{ . | markdownify }}</div>{{ end }}
      {{ .Page.Content }}
</div>
{{ end }}

Similarly, put the following code in layouts/partials/print/toc-li.html to remove the pg- prefix:

{{ $tpl := printf "partials/print/toc-li-%s.html" .Page.Type }}
{{ if templates.Exists $tpl }}
  {{ partial $tpl . }}
{{ else -}}
<li>{{ .sid}}: <a href="#{{.Page.File.UniqueID}}">{{ .Page.Title }}</a></li>
{{ end }}

Let me know if this works out for you!