search

orchidhq / Orchid

Build and deploy beautiful documentation sites that grow with you
https://orchid.run
GNU General Public License v3.0
514 stars 53 forks source link

Document OrchidSyntaxHighlighter #271

Closed DanySK closed 5 years ago

DanySK commented 5 years ago

The Orchid Syntax Highlighter documentation page says:

include a custom Pygments theme for the highlighting to work

However, no instruction on how to include the css for a custom theme is provided. It is also unclear that there is no need of adding assets/css/pygments.scss to your files, you just need to declare in the extraCss and the highlighting works -- yet it's not clear how to customize it.

I also tried to use PrismJS following the guide, but I was unable to enable highlighting. Is there any example of it at work?

cjbrooks12 commented 5 years ago

The SyntaxHighlighter plugin is bundled with a default stylesheet for Pygments, and when you declare assets/css/pygments.scss it adds that file as the styles for Pygments.

To customize the styles, simply make your own stylesheet in your local assets/css/ directory and add it with extraCss instead of the default one. You are free to name it something different, like the name of the theme, or if you give it the same name it will be used instead of the one defined in the plugin. Assets follow the same resource lookup order used for templates.

As an example for Prism, see here. This is work I'm doing to change to Prism over Pygments for the docs site.

DanySK commented 5 years ago

Thank you. I was able to setup Prism. However it's probably the case to improve the documentation (possibly providing the example from this issue).