Add syntax highlighting for gherkin inside the book

.gitignore

@@ -1,5 +1,5 @@
 /.idea/
-/.vscode/launch.json
+/.vscode/
 /*.iml
 .DS_Store
 

CHANGELOG.md

@@ -6,6 +6,20 @@ All user visible changes to `cucumber` crate will be documented in this file. Th
 
 
 
+## [0.18.1] · 2022-??-??
+[0.18.1]: /../../tree/v0.18.1
+
+[Diff](/../../compare/v0.18.0...v0.18.1) | [Milestone](/../../milestone/22)
+
+### Added
+
+- [Gherkin] syntax highlighting in the Book. ([#251]) 
+
+[#251]: /../../pull/251
+
+
+
+
 ## [0.18.0] · 2022-12-07
 [0.18.0]: /../../tree/v0.18.0
 
@@ -635,5 +649,6 @@ All user visible changes to `cucumber` crate will be documented in this file. Th
 
 [Cargo feature]: https://doc.rust-lang.org/cargo/reference/features.html
 [Cucumber Expressions]: https://cucumber.github.io/cucumber-expressions
+[Gherkin]: https://cucumber.io/docs/gherkin
 [MSRV]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field
 [Semantic Versioning 2.0.0]: https://semver.org

Makefile

@@ -134,6 +134,29 @@ book.build:
 	mdbook build book/ $(if $(call eq,$(out),),,-d $(out))
 
 
+# Build `highlight.js` library with Gherkin syntax support for Book.
+#
+# Usage:
+#	make book.highlight.js [ver=(10.7.3|<version>)]
+
+book-highlight-js-ver = $(or $(ver),10.7.3)
+book-highlight-js-tmp-dir := book/highlight.js
+
+book.highlight.js:
+	@rm -rf $(book-highlight-js-tmp-dir)
+	git clone https://github.com/highlightjs/highlight.js \
+	          $(book-highlight-js-tmp-dir)/
+	cd $(book-highlight-js-tmp-dir)/ && \
+	git checkout $(book-highlight-js-ver)
+	cd $(book-highlight-js-tmp-dir)/ && \
+	npm install
+	cd $(book-highlight-js-tmp-dir)/ && \
+	node tools/build.js :common gherkin
+	cp -f $(book-highlight-js-tmp-dir)/build/highlight.min.js \
+	      book/theme/highlight.js
+	rm -rf $(book-highlight-js-tmp-dir)
+
+
 # Serve Book on some port.
 #
 # Usage:
@@ -192,6 +215,6 @@ endif
 
 .PHONY: book docs fmt lint record test \
         cargo.doc cargo.fmt cargo.lint \
-        book.build book.serve book.test book.tests \
+        book.build book.highlight.js book.serve book.test book.tests \
         record.gif \
         test.cargo test.book

book/.gitignore

@@ -1,2 +1,3 @@
 /_rendered/
 /gh-pages/
+/highlight.js/

book/README.md

@@ -1,6 +1,6 @@
-# cucumber book
+# `cucumber` Book
 
-Book containing the [`cucumber`](https://crates.io/crates/cucumber) documentation.
+Book containing the [`cucumber` crate](https://crates.io/crates/cucumber) user guide.
 
 
 
@@ -10,7 +10,7 @@ Book containing the [`cucumber`](https://crates.io/crates/cucumber) documentatio
 
 ### Requirements
 
-The Book is built with [mdBook](https://github.com/rust-lang-nursery/mdBook).
+The Book is built with [mdBook].
 
 You can install it with:
 ```bash
@@ -42,6 +42,20 @@ make book
 The output will be in the `_rendered/` directory.
 
 
+### Syntax highlighting
+
+As the [default supported languages][1] for [mdBook]'s build of [`highlight.js`] don't include [Gherkin], we build our own version:
+```bash
+# from project root dir:
+make book.highlight.js
+
+# or concrete version:
+make book.highlight.js ver=10.7.3
+```
+
+> __WARNING__: [mdBook] doesn't work with [`highlight.js`] of versions > `10` (see [rust-lang/mdBook#1622](https://github.com/rust-lang/mdBook/issues/1622) for details).
+
+
 ### Running tests
 
 To run the tests validating all code examples in the book, run (from project root dir):
@@ -53,3 +67,12 @@ OUT_DIR=target mdbook test -L target/debug/deps
 # or via shortcut:
 make test.book
 ```
+
+
+
+
+[`highlight.js`]: https://github.com/highlightjs/highlight.js
+[Gherkin]: https://cucumber.io/docs/gherkin
+[mdBook]: https://github.com/rust-lang/mdBook
+
+[1]: https://rust-lang.github.io/mdBook/format/theme/syntax-highlighting.html#supported-languages