search

readthedocs / ext-theme

Read the Docs drop in replacement site templates
2 stars 2 forks source link

Add project: highlight yaml examples #369

Open humitos opened 3 months ago

humitos commented 3 months ago

I used highlight.js to highlight the examples when importing a project. It requires importing a CSS file that I'm not sure where to put it yet.

https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/dark.min.css

Besides, I need to know where to place the small chunk of JS code that I added to make this work.

Screenshot_2024-06-06_14-02-30

@agjohnson I would appreciate some directions here to clean up and finish this work.

Based on #368

humitos commented 3 months ago

I moved the code where I think it belongs. The only missing piece here is understanding how to include my CSS stylesheet file. Other than that, it seems that everything works as expected 👍🏼

humitos commented 3 months ago

Boom! I figured it out!

agjohnson commented 3 months ago

We are already using Pygments on the server side in other places. We should very likely continue with that pattern, I don't feel we should have two ways of highlighting.

You can see the integration HTTP exchange UI, templates, and views for examples of this. I'm guessing it will plug in easily here as well.

Here's one spot:

The pygments support in our theme already went through the process of matching the color theme too, which would also be required to support highlight.js.

agjohnson commented 3 months ago

Noted on the original issue too, the plan when this UI was first added was to come back and switch the examples with tabbed menus and use Pygments for highlighting:

A pygments solution would probably work best with a template filter, given these examples are hardcoded in templates. django-pygments might give us this already.

humitos commented 3 months ago

OK. The original issue said that either worked: pygments or a front-end solution. I will come back to this once I have some extra time and check the pygments solution. However, I will de-prioritize this work for now.

agjohnson commented 3 months ago

Adding a front end dependency works if pygments doesn't work for some reason, but it helps to keep patterns the same and dependencies minimal on the front end side if we can.