highlightjs-chapel
v0.1.0
Published
highlight.js support for Chapel
Downloads
45
Maintainers
Readme
This repo provides third-party highlight.js support for the Chapel language (https://chapel-lang.org).
Notes/Reminders to myself and potentially others
This is a third-party highlight.js package, which means that it won't be included in every distribution of highlight.js by default, but that, depending on the context, people may be able to opt in to it. I've taken the approach of getting something simple up and running quickly to get the basics working, but more time could be invested here to improve it over time.
Getting started for the first time
Make sure
node
andnpm
are available to you.On Mac:
brew install node
Clone the main highlight.js repository:
git clone https://github.com/highlightjs/highlight.js.git
(or create your own fork first and then clone that)
Install dependencies
$ cd .../highlight.js $ npm install
Create your own fork of this repo using the "Fork" button from https://github.com/chapel-lang/highlightjs-chapel
Clone your fork into the
extra
directory:$ cd extra $ git clone https://github.com/USERNAME/highlightjs-chapel
Make sure things work as expected:
npm run build_and_test
Specifically, at the end of this test run, you should see output for each of the tests in
test/markup/chapel/
, e.g.chapel ✓ should markup basic ✓ should markup strings
To modify the Chapel grammar and test it
Edit
src/languages/chapel.js
in this repo to your heart's content. See:https://highlightjs.readthedocs.io/en/latest/language-guide.html
for a high-level/so-so guide, or look at other languages to see what they do.
Build Chapel only from the highlight.js root directory by doing:
node tools/build.js -n chapel
Open tools/developer.html in your browser and paste code snippets into it to see how they work:
open tools/developer.html
Note that Chapel will not be auto-detected, so you'll need to select it manually.
Add any new test cases to test/markup/chapel/ in this repository as two files:
foo.txt
: the Chapel source codefoo.expect.txt
: the expected markup output
(where the expected markup can be copy-pasted from the developer.html tool in the previous step).
Make sure your new test works:
npm run build_and_test
To integrate the Chapel grammar into a Discourse Theme
Build the CDN version of highlight.js:
node tools/build.js -t cdn
Take a look at chapel.min.js:
emacs -nw extra/highlightjs-chapel/dist/chapel.min.js
Make a copy of the script and edit out the initial registerLanguage() call and closing braces/parens, also removing linefeeds, to get a single-line version of the script for pasting into the next step.
On the Discourse admin panel:
click to "Customize -> Themes"
select a theme to edit (syntax highlighting is specific to a theme and will need to be added to each theme that you want to support)
Under "Custom CSS/HTML" choose "Edit CSS/HTML"
Go to the "Head" section
NOTE: Last time I did this (Feb 6, 2024) the new script format didn't match the old as closely as I was expecting and I got nervous about potential highlight.js version mismatches, so I just copied the keywords section of the script into the old script to minimize differences. A little hacky, but it seemed to work.
Paste in / update the following script:
<script type="text/discourse-plugin" version="0.8.27"> // add Chapel language to HighlightJS // Must build highlight.js with "node tools/build.js -t cdn" const chapelLang = TODO: PASTE_FUNCTION_HERE!!! api.registerHighlightJSLanguage("chapel", chapelLang); </script>
where the function should have the form:
function(e){return{name:"Chapel",aliases:["chapel","chpl"],...}}
Under Settings->Posting, add "chapel" to the "highlighted languages" section. Optionally, consider also making "Chapel" the default code language.
Open questions:
- Does the registerHighlightJSLanguage() line need to be repeated for each triple-quote tag we want to recognize?
- Does each string passed to registerHighlightJSLanguage() need to be named distinctly in the "highlighted languages" section, or is it cognizant of the aliases in the language's definition.
TODO list for improving the grammar
easy: What other "built-ins" would we want to call out? (e.g.,
Locales
,here
,writeln
)I suspect our string forms could be beefed up to better handle escaped characters and the like
I think our numerical forms are missing some forms like binary, octal, and maybe hex(?) including hex floating point forms?
Other languages do more to call out constructs that create new scoped concepts like 'class', 'enum', 'proc', 'iter', etc. Should we?
Generally speaking, our grammar is much simpler than most other languages, making me think it's not as bulletproof. What more should we worry about for generality?
Other links that may be useful
Highlight.js resources:
language contributor checklist: https://highlightjs.readthedocs.io/en/latest/language-contribution.html
- third-party quickstart: https://github.com/highlightjs/highlight.js/blob/master/extra/3RD_PARTY_QUICK_START.md
general information on building and testing: https://highlightjs.readthedocs.io/en/latest/building-testing.html
issue where I asked for clarifications: https://github.com/highlightjs/highlight.js/issues/2800
Integration into Discourse resources:
The path I took to success (summarized above): https://meta.discourse.org/t/hack-to-install-a-new-language-for-highlight-js-on-a-hosted-discourse/55818/7
Another potential possibility:
- https://meta.discourse.org/t/integrating-a-customized-highlight-js-into-my-forum/48758
Integration into StackOverflow:
- Looks like a tough path, but: https://meta.stackexchange.com/questions/184108/what-is-syntax-highlighting-and-how-does-it-work/184109#184109