Add project: highlight yaml examples #369
Conversation
I used tabs to show different examples of YAML files, as suggested in #184. It looks great for an initial interactive approach. I like the tabs over the dropdown because it gives the user a clear idea there are more than Sphinx and MkDocs tools supported, which is a good marketing strategy, in my opinion. It also adds an "Others" option that's more generic and shows how to use `build.commands` in a generic way: install dependencies, build, copy assets under `$READTHDOCS_OUTPUT` directory.
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. Based on #368
|
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 👍🏼 |
|
Boom! I figured it out! |
npm run build
| <pre> | ||
| <code id="project-create-sample-sphinx" class="language-yaml highlight"> |
There was a problem hiding this comment.
highlight.js requires this to be pre > code and not the other way around 🤷🏼
|
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. |
|
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. |
|
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. |
|
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. |
I used
highlight.jsto 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.
@agjohnson I would appreciate some directions here to clean up and finish this work.
Based on #368