feat: Default theme for syntax highlighting

[jared-thoughtbot]

Summary

Apply a theme for syntax highlighting out-of-the-box, so code snippets are styled by default.

Motivation

I installed Bridgetown 1.0.0 following the guides. Fired up the server with bin/bridgetown start and was impressed to see the site, homepage and posts. I viewed the post and saw the mention of powerful support for code snippets but was disappointed to see the code snippet was not styled.

At first I thought I'd done something wrong. The implication of powerful support implies that it handles the colour styling for you. I tried to look through the docs and found a reference to the liquid syntax eg. {% highlight ruby %}. Tried that but it made no difference. I wanted to live in markdown syntax anyway and prefer eg. ```ruby

At this point I felt a bit lost and started randomly googling. Eventually I found the information I needed hidden in the Liquid Tags docs page Stylesheets for syntax highlighting. My mental model didn't associate this with Liquid which is why I didn't really explore this section of the documentation before. I do wonder if the syntax highlighting section could be lifted up out of the Liquid docs and placed elsewhere for better visibility?

Once I found these docs it was easy. I understood that there are many styles and I can easily copy one of the linked themes and use it.

But I still think having a default theme for code snippets would better meet new users' expectations. The default application already has some default styles. As long as we make it easy to change I think having some default is a better 'new app' experience than no styles at all. I believe this matches one of Bridgetown's core principles of Convention over configuration.

Guide-level explanation

Syntax highlighting

Code snippets are styled using a syntax-highlighting.css stylesheet in your styles directory (these styles are imported via your index.js file). By Default we use Github's theme, but you can use any CSS that's compatible with Pygments—example gallery here or from its repository.

```ruby
def print_hi(name)
  puts "Hi, #{name}"
end
print_hi('Tom')
#=> prints 'Hi, Tom' to STDOUT.

Becomes

![syntax-highlighting-styled](https://user-images.githubusercontent.com/80278561/157921094-2715aa6d-f6f3-4e74-9a17-0bb08c5f773f.png)

This section probably needs fleshing out but it's a start.

## Reference-level explanation

<!--
  This is the technical portion of the feature request. Explain the design in
  sufficient detail that:

  - Its interaction with other features is clear.
  - It is reasonably clear how the feature would be implemented.
  - Corner cases are dissected by example.

  If you do not know how to answer this, you can omit it. No worries!
-->

As an implementation suggestion I think a separate css file for syntax highlighting makes sense to encapsulate this in one place. Here's an example setup app (what I ended up with):

![bridgetown-syntax-files-suggestion](https://user-images.githubusercontent.com/80278561/157921538-8b6c963b-af65-473e-a3b5-084c239622db.png)

We want to make it clear how they can can change the styles and I had a go at adding some code comments (seen in the screenshot on the right).

## Drawbacks

<!--
  Why should we *not* do this?
-->

There may be some users that don't want syntax highlighting, or they want a different theme. I still feel _most_ users would expect some theme by default. To cater to all users we need to make it easy to change / remove.

## Unresolved Questions

<!--
  What related issues do you consider out of scope for this feature that could be
  addressed in the future independently of the solution that comes out of this
  feature?
-->

Which theme to use? For lack of a better option I might vote for Github's theme as it's well known. But I don't have strong opinions here.

[jaredcwhite]

Thanks for advocating for this @jared-thoughtbot, and I agree we should have a simple mechanism of adding in the necessary syntax CSS. Given the amount of effort you've put into this already, would you be willing to submit a PR?

[jared-thoughtbot]

@jaredcwhite Sure thing! I'll have a go and report back. I might have some time on Friday.

[ayushn21]

I'd briefly thought about this problem a few months ago but didn't end up spending any time on it. My dream UX for this is the user should be able to set the theme they want in bridgetown.config.yml and Bridgetown would magically add it to their site. How this could work though, I haven't got a clue.

Also, we use Rouge for syntax highlighting don't we? Not Pygments? Do we need to update our docs or have I not understood something properly?

[ayushn21]

For https://github.com/ayushn21/actiontext-syntax-highlighter, I copied over all the CSS theme files from the Rouge repo into my repo and I ship them with the library's npm package. I modified the themes CSS styles to target a data-theme attribute so multiple themes can be included and then used by setting data-theme on pre tag.

The user can @import the theme(s) they want in their CSS and set the default theme as a config setting.

If we bundle all the Rouge themes with the Bridgetown gem, perhaps there's a way to inject it into the CSS from a config setting. But I'm just spitballing here, not sure if any of this is viable! Just thought I'd share in case it helps in any way?

[jaredlt]

I've got a PR up to continue the discussion https://github.com/bridgetownrb/bridgetown/pull/516

@ayushn21 you mention some nice ideas, although I didn't try to tackle these in this first step. With any config option I assume some users will still want a way to fully customize it (away from any pre-set themes). I don't have any answers here. I guess it's just a UX problem to solve.

we use Rouge for syntax highlighting don't we? Not Pygments? Do we need to update our docs or have I not understood something properly?

I had a look into this and Rouge's "HTML output is compatible with stylesheets designed for Pygments."