Syntax highlighting for opam snippets (#190)

README.md

@@ -13,7 +13,7 @@ https://github.com/melange-re/melange.
 
 After cloning the repository, install the necessary JavaScript packages:
 
-```
+```bash
 yarn
 ```
 
@@ -25,7 +25,7 @@ Optionally, to run some of the tools to auto-generate parts of the
 documentation, you will need an opam switch with the required dependencies. To
 set it up, run:
 
-```
+```bash
 make init
 ```
 
@@ -39,13 +39,13 @@ generation"](#optional-tooling-for-docs-generation) section.
 
 To run the script:
 
-```
+```bash
 dune build @re
 ```
 
 To promote any changes to the original `md` file, one can run:
 
-```
+```bash
 dune build @re --auto-promote
 ```
 

docs/.vitepress/config.mts

@@ -14,6 +14,11 @@ const duneGrammar = JSON.parse(
   readFileSync(join(__dirname, "./dune.tmLanguage.json"), "utf8")
 );
 
+// https://github.com/ocamllabs/vscode-ocaml-platform/blob/master/syntaxes/opam.json
+const opamGrammar = JSON.parse(
+  readFileSync(join(__dirname, "./opam.tmLanguage.json"), "utf8")
+);
+
 const base = process.env.BASE || "unstable";
 
 // https://vitepress.dev/reference/site-config
@@ -33,7 +38,7 @@ export default defineConfig({
     hostname: `https://melange.re/${base}/`,
   },
   markdown: {
-    languages: [reasonGrammar, duneGrammar],
+    languages: [reasonGrammar, duneGrammar, opamGrammar],
   },
   themeConfig: {
     outline: { level: [2, 3] },

docs/.vitepress/opam.tmLanguage.json

@@ -0,0 +1,112 @@
+{
+  "name": "opam",
+  "scopeName": "source.ocaml.opam",
+  "fileTypes": ["opam"],
+  "patterns": [
+    { "include": "#comments" },
+    { "include": "#fields" },
+    { "include": "#values" }
+  ],
+  "repository": {
+    "comments": {
+      "patterns": [
+        {
+          "comment": "block comment",
+          "name": "comment.block.opam",
+          "begin": "\\(\\*",
+          "end": "\\*\\)"
+        },
+        {
+          "comment": "line comment",
+          "name": "comment.line.opam",
+          "begin": "#",
+          "end": "$"
+        }
+      ]
+    },
+
+    "fields": {
+      "comment": "labeled field",
+      "match": "^([[:word:]-]*[[:alpha:]][[:word:]-]*)(:)",
+      "captures": {
+        "1": { "name": "entity.name.tag.opam" },
+        "2": { "name": "keyword.operator.opam" }
+      }
+    },
+
+    "values": {
+      "patterns": [
+        {
+          "comment": "boolean literal",
+          "name": "constant.language.opam",
+          "match": "\\b(true|false)\\b"
+        },
+        {
+          "comment": "integer literal",
+          "name": "constant.numeric.decimal.opam",
+          "match": "(\\b|\\-?)[[:digit:]]+\\b"
+        },
+        {
+          "comment": "double-quote string literal",
+          "name": "string.quoted.double.opam",
+          "begin": "\"",
+          "end": "\"",
+          "patterns": [{ "include": "#string-elements" }]
+        },
+        {
+          "comment": "triple-double-quote string literal",
+          "name": "string.quoted.triple-double.opam",
+          "begin": "\"\"\"",
+          "end": "\"\"\"",
+          "patterns": [{ "include": "#string-elements" }]
+        },
+        {
+          "comment": "operator",
+          "name": "keyword.operator.opam",
+          "match": "[!=<>\\|&?:]+"
+        },
+        {
+          "comment": "identifier",
+          "match": "\\b([[:word:]+-]+)\\b",
+          "name": "variable.parameter.opam"
+        }
+      ]
+    },
+
+    "string-elements": {
+      "patterns": [
+        {
+          "comment": "escaped backslash",
+          "name": "constant.character.escape.opam",
+          "match": "\\\\\\\\"
+        },
+        {
+          "comment": "escaped quote or whitespace",
+          "name": "constant.character.escape.opam",
+          "match": "\\\\[\"ntbr\\n]"
+        },
+        {
+          "comment": "character from decimal ASCII code",
+          "name": "constant.character.escape.opam",
+          "match": "\\\\[[:digit:]]{3}"
+        },
+        {
+          "comment": "character from hexadecimal ASCII code",
+          "name": "constant.character.escape.opam",
+          "match": "\\\\x[[:xdigit:]]{2}"
+        },
+        {
+          "comment": "variable interpolation",
+          "name": "constant.variable.opam",
+          "begin": "%\\{",
+          "end": "}\\%"
+        },
+        {
+          "comment": "unknown escape sequence",
+          "name": "invalid.illegal.unknown-escape.opam",
+          "match": "\\\\."
+        }
+      ]
+    }
+  }
+}

docs/how-to-guides.md

@@ -32,7 +32,7 @@ section](./package-management.md).
 To get started with the library migration, let's create an `opam` file in your
 library's root folder with the minimum set of packages to start working:
 
-```text
+```opam
 opam-version: "2.0"
 synopsis: "My Melange library"
 description: "A library for Melange"
@@ -208,7 +208,7 @@ for testing. For this scenario, opam provides the `with-test` variable.
 Supposing we want to add `melange-jest` as a dependency to use for tests, you
 could add this in your library `opam` file:
 
-```text
+```opam
 depends: [
   "melange-jest" {with-test}
 ]

docs/package-management.md

@@ -84,7 +84,7 @@ for every platform.
 
 There is a necessary first step before using opam:
 
-```text
+```bash
 opam init -a
 ```
 
@@ -128,7 +128,7 @@ to be done by hand.
 
 A minimal `.opam` file looks like this:
 
-```text
+```opam
 opam-version: "2.0"
 name: "my-app"
 authors: "Louis"
@@ -157,21 +157,21 @@ in the project folder.
 
 If it does not exist, we can create it with:
 
-```text
+```bash
 opam switch create . 5.2.0 --deps-only
 ```
 
 If it exists, we can install the dependencies of the project with:
 
-```text
+```bash
 opam install . --deps-only
 ```
 
 ### Add new packages
 
 To add a new package to the opam switch, we can do:
 
-```text
+```bash
 opam install <package_name>
 ```
 
@@ -183,20 +183,20 @@ to be done by hand, by adding the name of the package in the `depends` field.
 This can be achieved with `opam pin`. For example, to pin a package to a
 specific commit on GitHub:
 
-```text
+```bash
 opam pin add reason-react.dev https://github.com/reasonml/reason-react.git#61bfbfaf8c971dec5152bce7e528d30552c70bc5
 ```
 
 Branch names can also be used.
 
-```text
+```bash
 opam pin add reason-react.dev https://github.com/reasonml/reason-react.git#feature
 ```
 
 For packages that are already published in the opam repository, a shortcut to
 pin to the latest version is to use the `--dev-repo` flag, e.g.
 
-```text
+```bash
 opam pin add melange.dev --dev-repo
 ```
 
@@ -212,13 +212,13 @@ There is one big difference compared to npm: opam stores a local copy of the
 opam repository, like `apt-get` does in Debian. So before doing any upgrades, we
 might want to update this copy before:
 
-```text
+```bash
 opam update
 ```
 
 Then, to upgrade the installed packages to the latest version, run:
 
-```text
+```bash
 opam upgrade <package_name>
 ```
 
@@ -231,7 +231,7 @@ You can use the [`with-dev-setup`
 field](https://opam.ocaml.org/doc/Manual.html#pkgvar-with-dev-setup) to define
 dependencies that are only required at development time. For example:
 
-```text
+```opam
 depends: [
   "ocamlformat" {with-dev-setup}
 ]
@@ -275,7 +275,7 @@ With this plugin, library authors can include constraints in the npm format
 inside the opam `depexts` field, for example, the `reason-react` opam file can
 include a section like this:
 
-```
+```opam
 depexts: [
   ["react" "react-dom"] {npm-version = "^17.0.0 || ^18.0.0"}
 ]
@@ -311,7 +311,7 @@ download, build and install opam packages in your switch. Remember that opam
 won't automatically add the dependency to `<your-project>.opam` file, so it must
 be added manually:
 
-```text
+```opam
 ...
 depends: [
   ...
@@ -378,7 +378,7 @@ git+https://github.com/melange-community/melange-fetch` will obtain
 `melange-fetch` from its Git repository and install it on your switch. Your
 `<your-project>.opam` file should then be updated in two places:
 
-```text
+```opam
 ...
 depends: [
   ...

playground/README.md

@@ -6,14 +6,14 @@ The Melange deps are specified in `documentation-site.opam`. Before building the
 
 From the project root:
 
-```
+```bash
 make install
 dune build @playground-assets
 ```
 
 Then, can work on the playground with:
 
-```
+```bash
 cd playground && yarn dev
 ```