Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rse/syntax
Unobtrusive Syntax Highlighting
https://github.com/rse/syntax
css html syntax-highlighting
Last synced: about 24 hours ago
JSON representation
Unobtrusive Syntax Highlighting
- Host: GitHub
- URL: https://github.com/rse/syntax
- Owner: rse
- Created: 2015-08-22T23:30:44.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-03-11T20:56:28.000Z (11 months ago)
- Last Synced: 2025-01-17T20:49:40.563Z (6 days ago)
- Topics: css, html, syntax-highlighting
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/syntax
- Size: 312 KB
- Stars: 7
- Watchers: 4
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
Syntax
======Unobtrusive Syntax Highlighting Library
About
-----*Syntax* is JavaScript library (for use in Node.js and Browser
environments) to apply Syntax Highlighting to a piece of input text --
usually source code. *Syntax* is based on four major design aspects:- **Good Language Support**:
The language-specific determination of comments, keywords and
literals should be a reasonable one. As syntax highlighting
is a science of its own, *Syntax* under the hood uses the excellent
[Highlight.js](https://highlightjs.org/) library.- **Unobtrusive Syntax Highlighting**:
The author, Ralf S. Engelschall, is a die-hard coder with a very
strict opinion when it comes to source code. One of his opinions is
that syntax highlighting has to be as unobstrusive as possible and
hence should highlight comments, keywords, and literals only. As a
consequence, *Syntax* intentionally(!) reduces the syntax highlighting
of the underlying [Highlight.js](https://highlightjs.org/) to just
these three kinds of syntactical elements.- **Anchors and Markers**:
In technical documentation it is regularily necessary to mark
arbitrary pieces of code and interspice reference anchors.
Unfortunately, whatever syntax is used for marking and anchors, this
always conflicts with the language-dependent syntax highlighting
as the marking and anchors renders the source code invalid. *Syntax*
resolves this problem by first reducing the (rich) input text to plain
text (by removing markings and anchors) and reapplying the markings
and anchors during output generation.- **Arbitrary Output Formats**:
Usually, having HTML or XML output format is sufficient, but sometimes
one also wants to support other formats and for this one needs the
precise offset information for anchors, markings, comments, keywords
and literals. *Syntax* supports this by internally using such an offset
based markup information and also exposing it in the API for external
consumption.Installation
------------#### Node environments (with NPM package manager):
```shell
$ npm install syntax
```#### Browser environments (with Bower package manager):
```shell
$ bower install syntax
```Example
-------The following is an example of *Syntax* in the Node.js environment:
```js
import Syntax from "syntax"let syntax = new Syntax({
language: "javascript",
cssPrefix: ""
})syntax.richtext(
"/* sample comment */\n" +
"={function foo}= (bar, quux) {\n" +
" return 42 =(1)=\n" +
"}\n"
)console.log(syntax.plaintext())
// +--- output: ---------------------------
// | /* sample comment */\n
// | function foo (bar, quux) {\n
// | return 42 \n
// | }\n
// +---------------------------------------console.log(require("util").inspect(syntax.markup(), { depth: null }))
// +--- output: ---------------------------
// | { anchor: { '1': 62 },
// | marker: [ [ 21, 33 ] ],
// | comment: [ [ 0, 20 ] ],
// | keyword: [ [ 21, 29 ], [ 52, 58 ] ],
// | literal: [ [ 59, 61 ] ] }
// +---------------------------------------console.log(syntax.html())
// +--- output: ---------------------------
// | /* sample comment */\n
// | function foo (bar, quux) {\n
// | return 42 \n
// | }\n
// +---------------------------------------
```For an example of *Syntax* in the Browser environment, see
[the included Sample project](sample/).Application Programming Interface (API)
---------------------------------------### Importing
- `import Syntax from "syntax"`
Import Syntax (ECMAScript 6 variant).- `var Syntax = require("syntax").default`
Import Syntax (CommonJS variant).### Class `Syntax`
- Constructor: `Syntax(config?: Object): Syntax`
Create a new syntax highlighting instance with
optional configuration settings.- Class Method: `Syntax.version(): { major: Number, minor: Number, micro: Number, date: Number }`:
Return the *Sugar* library version. The date is in numeric format `YYYYMMDD`.- Method: `Syntax#config(config?: Object): Syntax`
Set configuration settings. The available configuration options are:- `language` (default: `"auto"`):
Control the syntax highlighting of comments, keywords and literals.
By default, the language is guessed. See below for recognized
language identifiers. Set to `"none"` to enforce no syntax
highlighting of comments, keywords and literals at all (then
just markings and anchors are recognized).- `cssPrefix` (default: `"syntax-"`):
The CSS class prefix used in the HTML output.- `xmlPrefix` (default: `"syntax-"`):
The XML tag prefix used in the XML output.- `tabReplace` (default: `" "`):
The string TAB characters are replaced to in the output.- `newlineReplace` (default: `"\n"`):
The string newlines (`\r?\n`) are replaced to in the output.- `regexAnchorOpen` (default: `"=\\("`):
The regular expression (as a string) to recognize the opening of anchors.
Remember to extra-escape the special characters and to pass this as a
string, as *Syntax* internally has to assemble the regular expressions.- `regexAnchorClose` (default: `"\\)="`):
The regular expression (as a string) to recognize the closing of anchors.
Remember to extra-escape the special characters and to pass this as a
string, as *Syntax* internally has to assemble the regular expressions.- `regexMarkerOpen` (default: `"=\\{"`):
The regular expression (as a string) to recognize the opening of markings.
Remember to extra-escape the special characters and to pass this as a
string, as *Syntax* internally has to assemble the regular expressions.- `regexMarkerClose` (default: `"\\}="`):
The regular expression (as a string) to recognize the closing of markings.
Remember to extra-escape the special characters and to pass this as a
string, as *Syntax* internally has to assemble the regular expressions.- Method: `Syntax#richtext(input: String): Syntax`
Set the rich input text to process.- Method: `Syntax#plaintext(): String`
Method: `Syntax#plaintext(plaintext: String): Syntax`
Get or set the plain (output) text (the rich text after removing explicit markers and anchors).
The plain text is updated when `richtext()` is called. If using a custom
markup information it can be also set manually.- Method: `Syntax#markup(): Markup`
Method: `Syntax#markup(markup: Markup): Syntax`
Get or set the markup information. The markup information is updated
when `richtext()` is called. But a custom markup information can
be provided manually, too. The format of the markup information is:```
{
anchor: {
:
:
},
marker: [
[ , ]
:
],
comment: [
[ , ]
:
],
keyword: [
[ , ]
:
],
literal: [
[ , ]
:
]
}
```The positions are zero-based and end positions are at the first
character not included in the range.- Method: `Syntax#html(): String`
Apply the output markup information onto the output plain text and
render the result as HTML, based on interweaved
`` and `` tags.- Method: `Syntax#xml(): String`
Apply the output markup information onto the output plain text and
render the result as XML, based on interweaved
`<{xmlPrefix}{type}>` and `{xmlPrefix}{type}>` tags.Language Support
----------------By default, *Syntax* supports the following major languages (with the
`language` configuration option identifiers in parenthesis):1. Web Languages: XML/HTML (`xml`), CSS (`css`), LESS
(`less`), HTTP (`http`).2. Configuration Languages: JSON (`json`), YAML `yaml`, INI `ini`.
3. Progamming Languages: C/C++ (`cpp`), Objective-C (`objectivec`),
Swift (`swift`), C# (`cs`, `csharp`), F# (`fsharp`), Go (`go`), Java
(`java`), Kotlin (`kotlin`), Groovy (`groovy`), Scala (`scala`), JavaScript (`js`,
`javascript`), TypeScript (`typescript`), PHP (`php`), Perl (`perl`),
Python (`python`), Ruby (`ruby`).4. Shell Languages: Bourne Shell (`shell`), Bash (`bash`), PowerShell
(`powershell`), Makefile (`makefile`).5. Other Languages: SQL (`sql`), MarkDown (`markdown`), Diff (`diff`).
Those languages are pre-loaded in Node.js and bundled
with *Syntax* in the browser. In Node.js more languages
can be auto-loaded by just setting the `language`
configuration to its official identifier. See [Highlight.js'
sources](https://github.com/isagalaev/highlight.js/tree/master/src/languages)
for the identifiers (it is just the filename without the `.js`
extension). In browser environments, auto-loading additional languages
obviously does not work. There you have to bundle the additional
languages youself and call `hljs.registerLanguage()` yourself.Implementation Notice
---------------------Although *Syntax* is written in ECMAScript 6, it is transpiled to ECMAScript
5 and this way runs in really all(!) current (as of 2015) JavaScript
environments, of course.License
-------Copyright © 2015-2024 Dr. Ralf S. Engelschall (http://engelschall.com/)
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.