From 46955284933e5e503cda8689ded064635e79e730 Mon Sep 17 00:00:00 2001
From: Michael Newton
Date: Mon, 19 Oct 2020 13:13:49 -0600
Subject: [PATCH 001/142] (chore) typos and small documentation fixes (#2763)
- clarify location of common modes
- improve grammar and use consistent case for "JavaScript" and "highlight.js"
---
docs/api.rst | 2 +-
docs/language-guide.rst | 31 +++++++++++++++----------------
docs/language-requests.rst | 2 +-
docs/line-numbers.rst | 8 ++++----
docs/mode-reference.rst | 18 +++++++++---------
5 files changed, 30 insertions(+), 31 deletions(-)
diff --git a/docs/api.rst b/docs/api.rst
index 8b5ee44540..73fb131c65 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -59,7 +59,7 @@ Accepts a string with the highlighted markup.
Applies highlighting to a DOM node containing code.
This function is the one to use to apply highlighting dynamically after page load
-or within initialization code of third-party Javascript frameworks.
+or within initialization code of third-party JavaScript frameworks.
The function uses language detection by default but you can specify the language
in the ``class`` attribute of the DOM node. See the :doc:`class reference
diff --git a/docs/language-guide.rst b/docs/language-guide.rst
index 7f38fc02bf..38b0db659d 100644
--- a/docs/language-guide.rst
+++ b/docs/language-guide.rst
@@ -5,10 +5,10 @@ Highlighting overview
---------------------
Programming language code consists of parts with different rules of parsing: keywords like ``for`` or ``if``
-don't make sense inside strings, strings may contain backslash-escaped symbols like ``\"``
+don't make sense inside strings, strings may contain backslash-escaped symbols like ``\"``,
and comments usually don't contain anything interesting except the end of the comment.
-In highlight.js such parts are called "modes".
+In Highlight.js such parts are called "modes".
Each mode consists of:
@@ -19,7 +19,7 @@ Each mode consists of:
* …exotic stuff like another language inside a language
The parser's work is to look for modes and their keywords.
-Upon finding, it wraps them into the markup ``...``
+Upon finding them, it wraps them into the markup ``...``
and puts the name of the mode ("string", "comment", "number")
or a keyword group name ("keyword", "literal", "built-in") as the span's class name.
@@ -75,8 +75,8 @@ In the simple case language keywords can be defined with a string, separated by
Some languages have different kinds of "keywords" that might not be called as
such by the language spec but are very close to them from the point of view of a
syntax highlighter. These are all sorts of "literals", "built-ins", "symbols"
-and such. To define such keyword groups the attribute ``keywords`` becomes an
-object each property of which defines its own group of keywords:
+and such. To define such keyword groups, the attribute ``keywords`` becomes an
+object, each property of which defines its own group of keywords:
::
@@ -87,11 +87,11 @@ object each property of which defines its own group of keywords:
}
}
-The group name becomes the class name in the generated markup enabling different
-themeing for different kinds of keywords.
+The group name becomes the class name in the generated markup, enabling different
+theming for different kinds of keywords.
-To detect keywords highlight.js breaks the processed chunk of code into separate
-words — a process called lexing. By default "words" are matched with the regexp
+To detect keywords, highlight.js breaks the processed chunk of code into separate
+words — a process called lexing. By default, "words" are matched with the regexp
``\w+``, and that works well for many languages. Different lexing rules can be
defined by the magic ``$pattern`` attribute:
@@ -188,7 +188,7 @@ A classic example is an escaping sequence inside strings allowing them to contai
contains: [{begin: '\\\\.'}],
}
-For such modes ``className`` attribute should be omitted so they won't generate excessive markup.
+For such modes, the ``className`` attribute should be omitted so they won't generate excessive markup.
Mode attributes
@@ -253,10 +253,10 @@ Illegal symbols
---------------
Another way to improve language detection is to define illegal symbols for a mode.
-For example in Python first line of class definition (``class MyClass(object):``) cannot contain symbol "{" or a newline.
-Presence of these symbols clearly shows that the language is not Python and the parser can drop this attempt early.
+For example, in Python the first line of a class definition (``class MyClass(object):``) cannot contain the symbol ``{`` or a newline.
+The presence of these symbols clearly shows that the language is not Python, and the parser can drop this attempt early.
-Illegal symbols are defined as a a single regular expression:
+Illegal symbols are defined using a single regular expression:
::
@@ -269,14 +269,13 @@ Illegal symbols are defined as a a single regular expression:
Pre-defined modes and regular expressions
-----------------------------------------
-Many languages share common modes and regular expressions. Such expressions are defined in core highlight.js code
-at the end under "Common regexps" and "Common modes" titles. Use them when possible.
+Many languages share common modes and regular expressions. These expressions are defined in `lib/modes.js `_ and should be used whenever possible.
Regular Expression Features
---------------------------
-The goal of Highlight.js is to support whatever regex features Javascript itself supports. You're using real regular expressions, use them responsibly. That said, due to the design of the parser, there are some caveats. These are addressed below.
+The goal of Highlight.js is to support whatever regex features JavaScript itself supports. You're using real regular expressions, use them responsibly. That said, due to the design of the parser, there are some caveats. These are addressed below.
Things we support now that we did not always:
diff --git a/docs/language-requests.rst b/docs/language-requests.rst
index 07b8d8c98e..b00df95a01 100644
--- a/docs/language-requests.rst
+++ b/docs/language-requests.rst
@@ -2,7 +2,7 @@ On requesting new languages
===========================
This is a general answer to requests for adding new languages that appear from
-time to time in the highlight.js issue tracker and discussion group.
+time to time in the Highlight.js issue tracker and discussion group.
Highlight.js does not have a fundamental plan for implementing new languages
- i.e., the core team doesn't usually develop new languages. The core team
diff --git a/docs/line-numbers.rst b/docs/line-numbers.rst
index 674542d4ed..07b2f32db6 100644
--- a/docs/line-numbers.rst
+++ b/docs/line-numbers.rst
@@ -5,7 +5,7 @@ Highlight.js' notable lack of line numbers support is not an oversight but a
feature. Following is the explanation of this policy from the current project
maintainer (hey guys!):
- One of the defining design principles for highlight.js from the start was
+ One of the defining design principles for Highlight.js from the start was
simplicity. Not the simplicity of code (in fact, it's quite complex) but
the simplicity of usage and of the actual look of highlighted snippets on
HTML pages. Many highlighters, in my opinion, are overdoing it with such
@@ -15,7 +15,7 @@ maintainer (hey guys!):
reader from understanding it.
This is why it's not a straightforward decision: this new feature will not
- just make highlight.js better, it might actually make it worse simply by
+ just make Highlight.js better, it might actually make it worse simply by
making it look more bloated in blog posts around the Internet. This is why
I'm asking people to show that it's worth it.
@@ -28,9 +28,9 @@ maintainer (hey guys!):
are better is to set up some usability research on the subject. I doubt
anyone would bother to do it.
- Then there's maintenance. So far the core code of highlight.js is
+ Then there's maintenance. So far the core code of Highlight.js is
maintained by only one person — yours truly. Inclusion of any new code in
- highlight.js means that from that moment I will have to fix bugs in it,
+ Highlight.js means that from that moment I will have to fix bugs in it,
improve it further, make it work together with the rest of the code,
defend its design. And I don't want to do all this for the feature that I
consider "evil" and probably will never use myself.
diff --git a/docs/mode-reference.rst b/docs/mode-reference.rst
index afec714bb0..b79500ffd8 100644
--- a/docs/mode-reference.rst
+++ b/docs/mode-reference.rst
@@ -7,19 +7,19 @@ Types
Types of attributes values in this reference:
+------------+-------------------------------------------------------------------------------------+
-| identifier | String suitable to be used as a Javascript variable and CSS class name |
+| identifier | String suitable to be used as a JavaScript variable and CSS class name |
| | (i.e. mostly ``/[A-Za-z0-9_]+/``) |
+------------+-------------------------------------------------------------------------------------+
-| regexp | String representing a Javascript regexp. |
+| regexp | String representing a JavaScript regexp. |
| | Note that since it's not a literal regexp all back-slashes should be repeated twice |
+------------+-------------------------------------------------------------------------------------+
-| boolean | Javascript boolean: ``true`` or ``false`` |
+| boolean | JavaScript boolean: ``true`` or ``false`` |
+------------+-------------------------------------------------------------------------------------+
-| number | Javascript number |
+| number | JavaScript number |
+------------+-------------------------------------------------------------------------------------+
-| object | Javascript object: ``{ ... }`` |
+| object | JavaScript object: ``{ ... }`` |
+------------+-------------------------------------------------------------------------------------+
-| array | Javascript array: ``[ ... ]`` |
+| array | JavaScript array: ``[ ... ]`` |
+------------+-------------------------------------------------------------------------------------+
@@ -304,8 +304,8 @@ returnEnd
**type**: boolean
-Returns just found ending lexeme back into parser. This is used for example to parse Javascript embedded into HTML.
-A Javascript block ends with the HTML closing tag ```` that cannot be parsed with Javascript rules.
+Returns just found ending lexeme back into parser. This is used for example to parse JavaScript embedded into HTML.
+A JavaScript block ends with the HTML closing tag ```` that cannot be parsed with JavaScript rules.
So it is returned back into its parent HTML mode that knows what to do with it.
Since the parser is effectively goes back it's quite possible to create a infinite loop here so use with caution!
@@ -326,7 +326,7 @@ starts
The name of the mode that will start right after the current mode ends. The new mode won't be contained within the current one.
-Currently this attribute is used to highlight Javascript and CSS contained within HTML.
+Currently this attribute is used to highlight JavaScript and CSS contained within HTML.
Tags ``
```
+**unpkg** ([link](https://unpkg.com/browse/@highlightjs/cdn-assets/))
+
+```html
+
+
+```
+
**Note:** *The CDN-hosted `highlight.min.js` package doesn't bundle every language.* It would be
-very large. You can find our list "common" languages that we bundle by default on our [download page][5].
+very large. You can find our list "common" languages that we bundle by default on our [download page][5].
### Self Hosting
From f2ec26d939e1e99e78a2a508039b4c866570dc82 Mon Sep 17 00:00:00 2001
From: Josh Goebel
Date: Fri, 23 Oct 2020 18:25:28 -0400
Subject: [PATCH 006/142] chore(dev) add theme picker to the developer tool
(#2770)
---
CHANGES.md | 13 +++-
tools/developer.html | 157 +++++++++++++++++++++++++++++++++++++++----
2 files changed, 155 insertions(+), 15 deletions(-)
diff --git a/CHANGES.md b/CHANGES.md
index 4e5e74afc8..b87d8c043c 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,3 +1,12 @@
+## Version 10.4.0 (work in process)
+
+Dev Improvements:
+
+- chore(dev) add theme picker to the tools/developer tool (#2770) [Josh Goebel][]
+
+[Josh Goebel]: https://github.com/joshgoebel
+
+
## Version 10.3.1
Prior version let some look-behind regex sneak in, which does not work
@@ -10,6 +19,7 @@ Fix:
[Josh Goebel]: https://github.com/joshgoebel
[187e7cfc]: https://github.com/highlightjs/highlight.js/commit/187e7cfcb06277ce13b5f35fb6c37ab7a7b46de9
+
## Version 10.3.0
Language Improvements:
@@ -50,7 +60,8 @@ Deprecations:
[Chris Krycho]: https://github.com/chriskrycho
[David Pine]: https://github.com/IEvangelist
-[Josh Goebel]: https://github.com/joshgoebel
+
+
[Ryan Jonasson]: https://github.com/ryanjonasson
[Philipp Engel]: https://github.com/interkosmos
[Konrad Rudolph]: https://github.com/klmr
diff --git a/tools/developer.html b/tools/developer.html
index 86e9e63f8f..8e466fd7c1 100644
--- a/tools/developer.html
+++ b/tools/developer.html
@@ -66,6 +66,100 @@
Code
Language:
+ Theme:
@@ -85,12 +179,29 @@
Markup
`` that cannot be parsed with JavaScript rules.
@@ -314,7 +366,7 @@ Since the parser is effectively goes back it's quite possible to create a infini
contains
^^^^^^^^
-**type**: array
+- **type**: array
The list of sub-modes that can be found inside the mode. For detailed explanation see :doc:`Language definition guide `.
@@ -322,7 +374,7 @@ The list of sub-modes that can be found inside the mode. For detailed explanatio
starts
^^^^^^
-**type**: identifier
+- **type**: identifier
The name of the mode that will start right after the current mode ends. The new mode won't be contained within the current one.
@@ -333,7 +385,7 @@ Tags ``
<% } %>
-