diff --git a/building/config.json b/building/config.json index f3828366..bfa37a3a 100644 --- a/building/config.json +++ b/building/config.json @@ -242,6 +242,24 @@ "path": "building/tracks/new/launch.md", "title": "Launch!" }, + { + "uuid": "81169858-41f0-44da-875c-b1bb432f90b0", + "slug": "tracks/new/syntax-highlighting", + "path": "building/tracks/new/syntax-highlighting.md", + "title": "Enable syntax highlighting" + }, + { + "uuid": "374e2596-db7d-433d-b3c0-0f3dc75c453b", + "slug": "tracks/new/syntax-highlighting/static", + "path": "building/tracks/new/static-syntax-highlighting.md", + "title": "Static syntax highlighting" + }, + { + "uuid": "a443c67c-fb01-48f0-ab44-8710c065b3ea", + "slug": "tracks/new/syntax-highlighting/dynamic", + "path": "building/tracks/new/dynamic-syntax-highlighting.md", + "title": "Dynamic syntax highlighting" + }, { "uuid": "f697a7c1-ad33-460c-8458-18cd6d149920", "slug": "tracks/new/implement-tooling", diff --git a/building/tracks/new/README.md b/building/tracks/new/README.md index 6a92b590..2370be57 100644 --- a/building/tracks/new/README.md +++ b/building/tracks/new/README.md @@ -17,5 +17,6 @@ Once you've completed that step, the next steps are: - [Prepare for launch](/docs/building/tracks/new/prepare-for-launch) - [Find Maintainers](/docs/building/tracks/new/find-maintainers) - [Launch!](/docs/building/tracks/new/launch) +- [Enable syntax highlighting](/docs/building/tracks/new/syntax-highlighting) - [Implement additional tooling](/docs/building/tracks/new/implement-tooling) - [Prepare for open source contributions from strangers](/docs/building/tracks/new/prepare-for-contributions) diff --git a/building/tracks/new/dynamic-syntax-highlighting.md b/building/tracks/new/dynamic-syntax-highlighting.md new file mode 100644 index 00000000..e75b514f --- /dev/null +++ b/building/tracks/new/dynamic-syntax-highlighting.md @@ -0,0 +1,71 @@ +# Dynamic syntax highlighting + +Dynamic syntax highlighting is highlighting of code that the user can change. +There is only one place where this happens, and that is the online editor. + +```exercism/note +Code snippets, iterations, and the like are _static_ as the user can't change their code on the fly. +If you'd like to know more of how we handle static syntax highlighting, check the [static syntax highlighting docs](/docs/building/tracks/new/syntax-highlighting/static). +``` + +## Implementation + +Dynamic syntax highlighting is done using the [CodeMirror library](https://codemirror.net/). + +When adding support for your language, there are three options: + +1. The language is supported _out of the box_ by CodeMirror (i.e. listed as a [supported language](https://codemirror.net/5/mode/)). + If so, continue to the [Enable language](#enable-language) section. +2. The language is supported via an existing CodeMirror plugin. + If so, continue to the [Using an existing plugin](#using-an-existing-plugin) section. +3. The language is _not_ supported. + There are now three options: + 1. Write a CodeMirror plugin from scratch, as described in the [Create a new plugin](#create-a-new-plugin) section. + 2. Your language's syntax (closely) resembles another language's syntax (e.g. Unison's syntax resembles Haskell), in which case you could consider using the syntax highlighting of that language for your language. + See the [Enable language](#enable-language) section for more information. + 3. Don't have dynamic syntax highlighting. + +### Enable language + +To enable CodeMirror support for your language, start a topic on the forum (https://forum.exercism.org/c/exercism/building-exercism/125). +We (Exercism) will then create a Pull Request that enables CodeMirror support for your language on the website. + +### Using an existing plugin + +To use an existing plugin, it needs to be published on [NPM](https://www.npmjs.com/). + +If the plugin isn't published on NPM, you can either: + +1. Ask the plugin author if they want to publish on NPM. +2. Fork the repository and publish it yourself. +3. Have us (Exercism) fork the repository and we publish it. + To do so, open a topic on the forum requesting this (https://forum.exercism.org/c/exercism/building-exercism/125). + +```exercism/note +The CodeMirror website has a [list of community-built language plugins](https://codemirror.net/docs/community/#language). +``` + +The next step is to [Enable language](#enable-language). + +### Create a new plugin + +If you'd like to create plugin, you have two options for hosting: + +1. Create a repository on your personal account and publish it yourself. +2. Have us (Exercism) create a repository and let us publish it. + To do so, open a topic on the forum requesting this (https://forum.exercism.org/c/exercism/building-exercism/125). + +```exercism/note +You could consider forking the [codemirror/lang-example repository](https://github.com/codemirror/lang-example) which implements CodeMirror support for a simple language. +``` + +Once you have a repo, follow the [language package instructions](https://codemirror.net/examples/lang-package/) to implement the plugin. + +You'll then need to publish the plugin on [NPM](https://www.npmjs.com/). +The next step is to [Enable the language](#enable-language). + +### Use a different language + +Your language's syntax (closely) resembles another language's syntax, in which case you could consider using the syntax highlighting of that language for your language. +To do so, configure the track using the other language's CodeMirror plugin. +See the [Enable language](#enable-language) section for more information. diff --git a/building/tracks/new/static-syntax-highlighting.md b/building/tracks/new/static-syntax-highlighting.md new file mode 100644 index 00000000..66e1d950 --- /dev/null +++ b/building/tracks/new/static-syntax-highlighting.md @@ -0,0 +1,78 @@ +# Static syntax highlighting + +Static syntax highlighting is highlighting of code that the user _can't_ change. +This includes code snippets, iterations, and more. + +```exercism/note +The online editor does _not_ use static syntax highlighting as the user can change the code on the fly. +If you'd like to know more of how we handle syntax highlighting in the online editor, check the [dynamic syntax highlighting docs](/docs/building/tracks/new/syntax-highlighting/dynamic). +``` + +## Implementation + +Static syntax highlighting is done using the [highlightjs library](https://highlightjs.org/). + +When adding support for your language, there are three options: + +1. The language is supported _out of the box_ by highlightjs (i.e. listed as a [supported language](https://github.com/highlightjs/highlight.js/blob/main/SUPPORTED_LANGUAGES.md)). + If so, continue to the [Configuring track](#configuring-track) section. +2. The language is supported via an existing highlightjs plugin. + If so, continue to the [Using an existing plugin](#using-an-existing-plugin) section. +3. The language is _not_ supported. + There are now three options: + 1. Write a highlightjs plugin from scratch, as described in the [Create a new plugin](#create-a-new-plugin) section. + 2. Your language's syntax (closely) resembles another language's syntax (e.g. Unison's syntax resembles Haskell), in which case you could consider using the syntax highlighting of that language for your language. + See the [Configuring track](#configuring-track) section for more information. + 3. Don't have static syntax highlighting. + +### Configuring track + +To enable highlightjs support for your track's language, you'll need to modify the track's [config.json file](/docs/building/tracks/config-json). +Within the `config.json` file, add/set the `online_editor.highlightjs_language` key to the appropriate highlightjs language identifier (which can be found in the documentation). + +#### Example + +```json +{ + "online_editor": { + "highlightjs_language": "csharp" + } +} +``` + +### Using an existing plugin + +To use an existing plugin, it needs to be published on [NPM](https://www.npmjs.com/). +If the plugin isn't published on NPM, you can either: + +1. Ask the plugin author if they want to publish on NPM. +2. Fork the repository and publish it yourself. +3. Have us (Exercism) fork the repository and we publish it. + To do so, open a topic on the forum requesting this (https://forum.exercism.org/c/exercism/building-exercism/125). + +The next step is to [Enable the plugin](#enable-plugin). + +### Enable plugin + +To enable a plugin (which must be published on [NPM](https://www.npmjs.com/)), start a topic on the forum requesting us to add support for the plugin to the website (https://forum.exercism.org/c/exercism/building-exercism/125). +We (Exercism) will then create a Pull Request that adds the plugin to the website. +Once the PR is merged, you can enable highlightjs support by following the instructions in the [Configuring track](#configuring-track) section. + +### Create a new plugin + +If you'd like to create plugin, you have two options for hosting: + +1. Create a repository on your personal account and publish it yourself. +2. Have us (Exercism) create a repository and let us publish it. + To do so, open a topic on the forum requesting this (https://forum.exercism.org/c/exercism/building-exercism/125). + +Once you have a repo, follow the [language contribution instructions](https://highlightjs.readthedocs.io/en/latest/language-contribution.html) to implement the plugin. + +You'll then need to publish the plugin on [NPM](https://www.npmjs.com/). +The next step is to [Enable the plugin](#enable-plugin). + +### Use a different language + +Your language's syntax (closely) resembles another language's syntax, in which case you could consider using the syntax highlighting of that language for your language. +To do so, configure the track to use the other language's highlightjs language identifier. +See the [Configuring track](#configuring-track) section for more information. diff --git a/building/tracks/new/syntax-highlighting.md b/building/tracks/new/syntax-highlighting.md new file mode 100644 index 00000000..3785bded --- /dev/null +++ b/building/tracks/new/syntax-highlighting.md @@ -0,0 +1,12 @@ +# Syntax highlighting + +There are two types of syntax highlighting on the website: + +1. Highlighting _static_ code (code snippets, iterations, and such). + Check [static syntax highlighting docs](/docs/building/tracks/new/syntax-highlighting/static) for more information. +2. Highlighting _dynamic_ code (the online editor). + Check [dynamic syntax highlighting docs](/docs/building/tracks/new/syntax-highlighting/dynamic) for more information. + +```exercism/note +The requirements for static and dynamic syntax highlighting are _very_ different, which is why they use different libraries. +```