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

Implement an interlinking short-hand syntax #328

Open
machow opened this issue Jan 22, 2024 · 2 comments
Open

Implement an interlinking short-hand syntax #328

machow opened this issue Jan 22, 2024 · 2 comments
Labels

Comments

@machow
Copy link
Owner

machow commented Jan 22, 2024

Based on discussion in #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 machow added the .epic label Jan 22, 2024
@machow
Copy link
Owner Author

machow commented Jan 25, 2024

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

@gadenbuie
Copy link

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
Status: No status
Development

No branches or pull requests

2 participants