search

mdn / yari

The platform code behind MDN Web Docs
Mozilla Public License 2.0
1.19k stars 510 forks source link

Link keywords in code samples to corresponding MDN pages #1452

Open chrisdavidmills opened 4 years ago

chrisdavidmills commented 4 years ago

@mattiapontonio commented on Wed Oct 14 2020

Hello,

Just a little suggestion that can be an Epic.

Provide automatic references from the CSS rendered snippets to the property / statment MDN page. Maybe a tooltip or something not invasive. GitHub made something similar with the web version with the class definitions, it provides internal links in the repository.

peterbe commented 4 years ago

I guess the proper solution, to turn a snippet into deep linked HTML is that you'd first need to properly parse the snippet's code and as you loop over tokens, you attempt to look them up as possibly individual pages. Would be really cool but not trivial.

peterbe commented 4 years ago

I love it! It would certainly be so cool. And not totally impossible either. Definitely some uphill engineering battles.

First all, this is how the rendering currently works in Yari:

  1. The content is just HTML with a <pre> tag.
  2. Then, we consume this HTML blog with cheerio and we fish out the pre tags. And for each one, we analyze the class attribute to figure out which lexer to use for Prismjs.
  3. Swap out the content of the <pre> tag for the HTML string that Prismjs produces.
  4. End.

So we know it's CSS based on that <pre class="brush:css .. and that means you COULD loop over every span.token.property and inject either a onMouseOver or a onClick which could tag the span tag's text and do a lookup for a page based on that string.

I can see benefits in doing all of this on the client and I can see benefits of doing all of this on the server. We could start small and "taste" it to see what feels right.

Ryuno-Ki commented 4 years ago

Funnily, this reminds me on why it took a long time to build a tiny link preview on Wikipedia.

Perhaps there are lessons to learn from them?

peterbe commented 4 years ago

Would you be interested in trying to formally submit a PR to Yari that does this fully?

peterbe commented 4 years ago

I need some grant or something? (I'm relatevly new to GitHub flows)

None. You just need to check out Yari and set it up to run locally and then you can work from there.

peterbe commented 4 years ago

Thank you but that prototype (thank you) is far from anywhere near being integrated. To make this work, we'll need a lot more thought and breadth for it to work at scale and to work nicely for all users and all types of content. There's no need to rush. The idea is great (mind you, you're not the first one to propose it) but that's the easy part. Now someone needs to find the time to set aside for building a solution that solves this nicely at scale for all pages where it applies.

By the way, in the English actively maintained content (~12k documents) we have 29,352 <pre> tags. And 4,948 of them are CSS code snippets.