{"id":24558036,"url":"https://github.com/rse/syntax","last_synced_at":"2025-04-19T09:58:43.994Z","repository":{"id":58227914,"uuid":"41228179","full_name":"rse/syntax","owner":"rse","description":"Unobtrusive Syntax Highlighting","archived":false,"fork":false,"pushed_at":"2024-03-11T20:56:28.000Z","size":319,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-06T00:43:02.444Z","etag":null,"topics":["css","html","syntax-highlighting"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/syntax","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-08-22T23:30:44.000Z","updated_at":"2024-03-11T20:56:31.000Z","dependencies_parsed_at":"2024-06-19T03:04:18.182Z","dependency_job_id":"362a6e62-4db5-408a-aff9-dd36888261ef","html_url":"https://github.com/rse/syntax","commit_stats":null,"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fsyntax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fsyntax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fsyntax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rse%2Fsyntax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rse","download_url":"https://codeload.github.com/rse/syntax/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249108897,"owners_count":21214085,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css","html","syntax-highlighting"],"created_at":"2025-01-23T05:47:14.346Z","updated_at":"2025-04-19T09:58:43.975Z","avatar_url":"https://github.com/rse.png","language":"JavaScript","readme":"\nSyntax\n======\n\nUnobtrusive Syntax Highlighting Library\n\n\u003cimg src=\"sample/screenshot.png\" alt=\"\"/\u003e\n\n\u003cp/\u003e\n\u003cimg src=\"https://nodei.co/npm/syntax.png?downloads=true\u0026stars=true\" alt=\"\"/\u003e\n\n\u003cp/\u003e\n\u003cimg src=\"https://david-dm.org/rse/syntax.png\" alt=\"\"/\u003e\n\nAbout\n-----\n\n*Syntax* is JavaScript library (for use in Node.js and Browser\nenvironments) to apply Syntax Highlighting to a piece of input text --\nusually source code. *Syntax* is based on four major design aspects:\n\n- **Good Language Support**:\n  The language-specific determination of comments, keywords and\n  literals should be a reasonable one. As syntax highlighting\n  is a science of its own, *Syntax* under the hood uses the excellent\n  [Highlight.js](https://highlightjs.org/) library.\n\n- **Unobtrusive Syntax Highlighting**:\n  The author, Ralf S. Engelschall, is a die-hard coder with a very\n  strict opinion when it comes to source code. One of his opinions is\n  that syntax highlighting has to be as unobstrusive as possible and\n  hence should highlight comments, keywords, and literals only. As a\n  consequence, *Syntax* intentionally(!) reduces the syntax highlighting\n  of the underlying [Highlight.js](https://highlightjs.org/) to just\n  these three kinds of syntactical elements.\n\n- **Anchors and Markers**:\n  In technical documentation it is regularily necessary to mark\n  arbitrary pieces of code and interspice reference anchors.\n  Unfortunately, whatever syntax is used for marking and anchors, this\n  always conflicts with the language-dependent syntax highlighting\n  as the marking and anchors renders the source code invalid. *Syntax*\n  resolves this problem by first reducing the (rich) input text to plain\n  text (by removing markings and anchors) and reapplying the markings\n  and anchors during output generation.\n\n- **Arbitrary Output Formats**:\n  Usually, having HTML or XML output format is sufficient, but sometimes\n  one also wants to support other formats and for this one needs the\n  precise offset information for anchors, markings, comments, keywords\n  and literals. *Syntax* supports this by internally using such an offset\n  based markup information and also exposing it in the API for external\n  consumption.\n\nInstallation\n------------\n\n#### Node environments (with NPM package manager):\n\n```shell\n$ npm install syntax\n```\n\n#### Browser environments (with Bower package manager):\n\n```shell\n$ bower install syntax\n```\n\nExample\n-------\n\nThe following is an example of *Syntax* in the Node.js environment:\n\n```js\nimport Syntax from \"syntax\"\n\nlet syntax = new Syntax({\n    language: \"javascript\",\n    cssPrefix: \"\"\n})\n\nsyntax.richtext(\n    \"/* sample comment */\\n\" +\n    \"={function foo}= (bar, quux) {\\n\" +\n    \"    return 42 =(1)=\\n\" +\n    \"}\\n\"\n)\n\nconsole.log(syntax.plaintext())\n// +--- output: ---------------------------\n// | /* sample comment */\\n\n// | function foo (bar, quux) {\\n\n// |     return 42 \\n\n// | }\\n\n// +---------------------------------------\n\nconsole.log(require(\"util\").inspect(syntax.markup(), { depth: null }))\n// +--- output: ---------------------------\n// | { anchor:  { '1': 62 },\n// |   marker:  [ [ 21, 33 ] ],\n// |   comment: [ [ 0, 20 ] ],\n// |   keyword: [ [ 21, 29 ], [ 52, 58 ] ],\n// |   literal: [ [ 59, 61 ] ] }\n// +---------------------------------------\n\nconsole.log(syntax.html())\n// +--- output: ---------------------------\n// | \u003cspan class=\"comment\"\u003e/* sample comment */\u003c/span\u003e\\n\n// | \u003cspan class=\"keyword\"\u003e\u003cspan class=\"marker\"\u003efunction\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"marker\"\u003e foo\u003c/span\u003e (bar, quux) {\\n\n// |     \u003cspan class=\"keyword\"\u003ereturn\u003c/span\u003e \u003cspan class=\"literal\"\u003e42\u003c/span\u003e \u003cspan class=\"anchor anchor-1\"\u003e\u003c/span\u003e\\n\n// | }\\n\n// +---------------------------------------\n```\n\nFor an example of *Syntax* in the Browser environment, see\n[the included Sample project](sample/).\n\nApplication Programming Interface (API)\n---------------------------------------\n\n### Importing\n\n- `import Syntax from \"syntax\"`\u003cbr/\u003e\n   Import Syntax (ECMAScript 6 variant).\n\n- `var Syntax = require(\"syntax\").default`\u003cbr/\u003e\n   Import Syntax (CommonJS variant).\n\n### Class `Syntax`\n\n- Constructor: `Syntax(config?: Object): Syntax`\u003cbr/\u003e\n  Create a new syntax highlighting instance with\n  optional configuration settings.\n\n- Class Method: `Syntax.version(): { major: Number, minor: Number, micro: Number, date: Number }`:\u003cbr/\u003e\n  Return the *Sugar* library version. The date is in numeric format `YYYYMMDD`.\n\n- Method: `Syntax#config(config?: Object): Syntax`\u003cbr/\u003e\n  Set configuration settings. The available configuration options are:\n\n   - `language` (default: `\"auto\"`):\u003cbr/\u003e\n     Control the syntax highlighting of comments, keywords and literals.\n     By default, the language is guessed. See below for recognized\n     language identifiers. Set to `\"none\"` to enforce no syntax\n     highlighting of comments, keywords and literals at all (then\n     just markings and anchors are recognized).\n\n   - `cssPrefix` (default: `\"syntax-\"`):\u003cbr/\u003e\n     The CSS class prefix used in the HTML output.\n\n   - `xmlPrefix` (default: `\"syntax-\"`):\u003cbr/\u003e\n     The XML tag prefix used in the XML output.\n\n   - `tabReplace` (default: `\"    \"`):\u003cbr/\u003e\n     The string TAB characters are replaced to in the output.\n\n   - `newlineReplace` (default: `\"\\n\"`):\u003cbr/\u003e\n     The string newlines (`\\r?\\n`) are replaced to in the output.\n\n   - `regexAnchorOpen` (default: `\"=\\\\(\"`):\u003cbr/\u003e\n     The regular expression (as a string) to recognize the opening of anchors.\n     Remember to extra-escape the special characters and to pass this as a\n     string, as *Syntax* internally has to assemble the regular expressions.\n\n   - `regexAnchorClose` (default: `\"\\\\)=\"`):\u003cbr/\u003e\n     The regular expression (as a string) to recognize the closing of anchors.\n     Remember to extra-escape the special characters and to pass this as a\n     string, as *Syntax* internally has to assemble the regular expressions.\n\n   - `regexMarkerOpen` (default: `\"=\\\\{\"`):\u003cbr/\u003e\n     The regular expression (as a string) to recognize the opening of markings.\n     Remember to extra-escape the special characters and to pass this as a\n     string, as *Syntax* internally has to assemble the regular expressions.\n\n   - `regexMarkerClose` (default: `\"\\\\}=\"`):\u003cbr/\u003e\n     The regular expression (as a string) to recognize the closing of markings.\n     Remember to extra-escape the special characters and to pass this as a\n     string, as *Syntax* internally has to assemble the regular expressions.\n\n- Method: `Syntax#richtext(input: String): Syntax`\u003cbr/\u003e\n  Set the rich input text to process.\n\n- Method: `Syntax#plaintext(): String`\u003cbr/\u003e\n  Method: `Syntax#plaintext(plaintext: String): Syntax`\u003cbr/\u003e\n  Get or set the plain (output) text (the rich text after removing explicit markers and anchors).\n  The plain text is updated when `richtext()` is called. If using a custom\n  markup information it can be also set manually.\n\n- Method: `Syntax#markup(): Markup`\u003cbr/\u003e\n  Method: `Syntax#markup(markup: Markup): Syntax`\u003cbr/\u003e\n  Get or set the markup information. The markup information is updated\n  when `richtext()` is called. But a custom markup information can\n  be provided manually, too. The format of the markup information is:\n\n    ```\n    {\n        anchor:  {\n            \u003creference: String\u003e: \u003cposition: Number\u003e\n            :\n        },\n        marker: [\n            [ \u003cstart-position: Number\u003e, \u003cend-position: Number\u003e ]\n            :\n        ],\n        comment: [\n            [ \u003cstart-position: Number\u003e, \u003cend-position: Number\u003e ]\n            :\n        ],\n        keyword: [\n            [ \u003cstart-position: Number\u003e, \u003cend-position: Number\u003e ]\n            :\n        ],\n        literal: [\n            [ \u003cstart-position: Number\u003e, \u003cend-position: Number\u003e ]\n            :\n        ]\n    }\n    ```\n\n  The positions are zero-based and end positions are at the first\n  character not included in the range.\n\n- Method: `Syntax#html(): String`\u003cbr/\u003e\n  Apply the output markup information onto the output plain text and\n  render the result as HTML, based on interweaved\n  `\u003cspan class=\"{cssPrefix}{type}\"\u003e` and `\u003c/span\u003e` tags.\n\n- Method: `Syntax#xml(): String`\u003cbr/\u003e\n  Apply the output markup information onto the output plain text and\n  render the result as XML, based on interweaved\n  `\u003c{xmlPrefix}{type}\u003e` and `\u003c/{xmlPrefix}{type}\u003e` tags.\n\nLanguage Support\n----------------\n\nBy default, *Syntax* supports the following major languages (with the\n`language` configuration option identifiers in parenthesis):\n\n1. Web Languages: XML/HTML (`xml`), CSS (`css`), LESS\n   (`less`), HTTP (`http`).\n\n2. Configuration Languages: JSON (`json`), YAML `yaml`, INI `ini`.\n\n3. Progamming Languages: C/C++ (`cpp`), Objective-C (`objectivec`),\n   Swift (`swift`), C# (`cs`, `csharp`), F# (`fsharp`), Go (`go`), Java\n   (`java`), Kotlin (`kotlin`), Groovy (`groovy`), Scala (`scala`), JavaScript (`js`,\n   `javascript`), TypeScript (`typescript`), PHP (`php`), Perl (`perl`),\n   Python (`python`), Ruby (`ruby`).\n\n4. Shell Languages: Bourne Shell (`shell`), Bash (`bash`), PowerShell\n   (`powershell`), Makefile (`makefile`).\n\n5. Other Languages: SQL (`sql`), MarkDown (`markdown`), Diff (`diff`).\n\nThose languages are pre-loaded in Node.js and bundled\nwith *Syntax* in the browser. In Node.js more languages\ncan be auto-loaded by just setting the `language`\nconfiguration to its official identifier. See [Highlight.js'\nsources](https://github.com/isagalaev/highlight.js/tree/master/src/languages)\nfor the identifiers (it is just the filename without the `.js`\nextension). In browser environments, auto-loading additional languages\nobviously does not work. There you have to bundle the additional\nlanguages youself and call `hljs.registerLanguage()` yourself.\n\nImplementation Notice\n---------------------\n\nAlthough *Syntax* is written in ECMAScript 6, it is transpiled to ECMAScript\n5 and this way runs in really all(!) current (as of 2015) JavaScript\nenvironments, of course.\n\nLicense\n-------\n\nCopyright \u0026copy; 2015-2024 Dr. Ralf S. Engelschall (http://engelschall.com/)\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n\"Software\"), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be included\nin all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\nCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frse%2Fsyntax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frse%2Fsyntax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frse%2Fsyntax/lists"}