Implement an interlinking short-hand syntax

machow commented 10 months ago

Based on discussion in https://github.com/machow/quartodoc/issues/315, it would be nice to allow a interlinks short-hand, to shorten links like [](`target`).

The main reason for this is that the longform is useful for customizing display name (e.g. [some name](`target`)), but cumbersome otherwise.

It seems like two important factors are:

Easy and quick to use.
Does not conflict too much with things people want rendered differently in quarto.
- E.g. if we use `:target` as a shorthand, then it will become hard to represent the literal code block :target.
- I'm onboard with a little overlap / conflict, if it makes life a lot nicer ;)

machow commented 9 months ago

@schloerke brought up :`target` seeming nice--but if we're worried about conflict we could use the very distinct ::`target` with two colons.

gadenbuie commented 1 month ago

Would it be a lot of overhead to just look through all inline code nodes and make them interlinks if they match? e.g.

This object inherits from `pydantic.BaseModel` and includes...

...use the `theme` argument of `shiny.express.ui.page_opts` to set the app theme.

A problem with the current interlinks syntax (besides the Sphinx syntax) is that most IDE hovercard implementations will treat quartodoc's interlink syntax as straight markdown, so unless you repeat the function name, e.g. [pydantic.BaseModel](`pydantic.BaseModel`), the text will be rendered with a blank spot where the empty link is.

In other words, if it's not prohibitive from a performance perspective, using regular inline code has the advantage of being a progressive enhancement. If quartodoc's interlinks filters are present they can be promoted to links; otherwise in all other situations the text renders as desired just without the link.

machow / quartodoc

Implement an interlinking short-hand syntax #328