Pkgdown: Pull out autolinking code into separate package

[hadley]

With minimal dependencies, making it easier to use in more places (e.g. bookdown, blogdown, ...)

[hadley]

If we do this, I think it's worth overhauling the overall syntax highlighting and autolinking process:

• Instead of using the highlight package, highlight use getParseData() and the same approach as prettycode

• Instead of the three current approaches (one for examples, one for <code>, and one for already highlighted <pre> blocks), switch to a unified approach based on post-processing <pre class="r"> (and suppressing the default syntax highlighting in pandoc).

The disadvantage of this would be that you'd lose pandoc's highlighting of other languages, but we could maybe build that back in by using highlite.

[maelle]

Not sure if relevant, but maybe, https://yihui.org/printr/#help-pages that @cderv helped me re-discover. I'm putting this here because on top of linking, a separate package could help with generating some sort of preview of the help page for e.g. hover?

[maelle]

I'd really like to help with the autolinking feature/package, if it makes sense. If not, sorry for spamming the thread!

In a Hugo website (so blogdown, hugodown), what could happen is

• autolink(pkg::fun) gets knitted to {{< showdoc "pkg::fun" >}} and creates a well-named file under data/ with the URL, title, description of the function.
• the shortcode showdoc uses the file under data, and a data template to link to a reference page / add a title on the link etc.
  I'm thinking about it because of the work by @jemus42 on a package shortcode.

[hadley]

I think it would be better to first figure out how the basic integration with hugo would work, before thinking about advanced previews (which I'd be generally hesitant to add because it's going to have to assume a lot about the theme).

[maelle]

By "basic integration with hugo" you mean going from autolink(pkg::fun) to ![pkg::fun()](link) by knitting an Rmd, right?

[hadley]

IMO, it has to work like pkgdown, i.e. the linking needs to be fully automated, not requiring any user intervention (except at the config/theme level). So that likely requires a transformation pass _after_ the .md has been converted to html (that's how pkgdown works currently)

[maelle]

Ah, ok! I disagree for blog posts, where that'd be a bit too much for me and where I'd prefer to ask for an autolink for functions/packages with intent when writing, but will find the tool useful despite that, especially the part that generates the link. :-)

In Hugo to change the html as far as I can tell you need to use a regex and a partial hack like this one.

[hadley]

@maelle so you don't want ``` blocks to be highlighted? To me, that one of the big advantages of autolinking.

But thinking about it more, the highlighting can't occur after html rendering, because then you'd lose the ability to get netlify previews. Instead, we'd need a post processing hook that takes ```R blocks and syntax highlights to generate HTML.

[maelle]

oooh you mean autolinking _inside_ code chunks? Ah, in blog posts I only dream of automatic links for mentions of packages and functions in text. Sorry for not being clearer. So I think we want two different things with the link, I want a function creating a Hugo shortcode or a Markdown link in text, and you're speaking about a knitr source hook.

[maelle]

In e.g. hugodown I wonder whether you could take advantage of having defined an output format to also define knitr hooks to go with that?

[maelle]

Not sure it'd actually work with a knitr source hook :thinking:

In Hugo it's really too bad there's no render hook for code blocks, that'd be easier. https://gohugo.io/getting-started/configuration-markup/#render-hook-templates

[maelle]

https://github.com/gohugoio/hugo/issues/6702

[hadley]

If you want to do it explicitly, I don't think you need pkgdown at all, since it's relatively simple enough to construct the link if you know the package and function name. A source hook would mean that you needed R installed on the compute doing the rendering, which means that it wouldn't work on netlify, which I think makes it a no go.

[hadley]

@maelle I made some notes about how I would implement this in hugodown at https://github.com/r-lib/hugodown/issues/17

[hadley]

(The latest version of pkgdown now uses highlight_text() so the second bullet point above has already been resolved)

[hadley]

Now happening in https://github.com/r-lib/downlit