eecs485staff / primer-spec

A Jekyll theme for sites with content-heavy pages
https://eecs485staff.github.io/primer-spec/
MIT License
22 stars 13 forks source link

[Code blocks] Magic Comments to mark highlight ranges #218

Closed seshrs closed 2 years ago

seshrs commented 2 years ago

Context

While researching other static site generators in #213, I discovered a really cool syntax for highlighting code block lines in Docusaurus.

This PR adds the ability to highlight code block lines using "magic comments". Primer Spec will recognize code block lines with comments primer-spec-highlight-start and primer-spec-highlight-end, and will automatically ensure that the lines in between are highlighted!

This only works with code blocks with syntax-highlighting, and only for pages built using Jekyll.

Validation

Check out the demo preview URL: https://preview.sesh.rs/previews/eecs485staff/primer-spec/218/demo/enhanced-code-blocks.html#markdown-source-for-magic-comments-6

It contains the following code block:

```python
x = {
  # primer-spec-highlight-start
  # This dict refers John, whose age is 30
  "name": "John",
  "age": 30,
  # primer-spec-highlight-end
  "cars": [
    {"model": "BMW 230", "mpg": 27.5},
    {"model": "Ford Edge", "mpg": 24.1}
  ]
}


Which renders without the magic comments, and with the correct lines highlighted:
> <img width="1017" alt="image" src="https://user-images.githubusercontent.com/12139762/196071672-13d21719-4b79-46dd-8126-00e259ed58a8.png#gh-light-mode-only">
> <img width="1015" alt="image" src="https://user-images.githubusercontent.com/12139762/196071635-67fa956e-f27d-4cbb-a3ab-36bd4c5d0773.png#gh-dark-mode-only">

I also locally tested the following scenarios:
- HTML and JS code blocks (with different comment syntax)
- Code blocks with both magic comments *and* a `data-highlight` attribute
github-actions[bot] commented 2 years ago

The spec from this PR is available at https://preview.sesh.rs/previews/eecs485staff/primer-spec/218/.

(Available until Thu Nov 17 2022.)