{"id":23782555,"url":"https://github.com/roydejong/shortcode-tree","last_synced_at":"2026-03-02T21:06:36.633Z","repository":{"id":57358741,"uuid":"111113136","full_name":"roydejong/shortcode-tree","owner":"roydejong","description":"node module for parsing generic shortcodes into a tree structure","archived":false,"fork":false,"pushed_at":"2023-04-19T12:57:23.000Z","size":139,"stargazers_count":4,"open_issues_count":5,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-06T02:05:52.338Z","etag":null,"topics":["bbcode","bbcode-parser","nodejs","nodejs-modules","shortcode","shortcodes","tokenizing-parser"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/roydejong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-11-17T14:33:37.000Z","updated_at":"2022-05-22T11:19:05.000Z","dependencies_parsed_at":"2022-09-26T16:31:19.006Z","dependency_job_id":null,"html_url":"https://github.com/roydejong/shortcode-tree","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roydejong%2Fshortcode-tree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roydejong%2Fshortcode-tree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roydejong%2Fshortcode-tree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roydejong%2Fshortcode-tree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roydejong","download_url":"https://codeload.github.com/roydejong/shortcode-tree/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232076654,"owners_count":18469237,"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":["bbcode","bbcode-parser","nodejs","nodejs-modules","shortcode","shortcodes","tokenizing-parser"],"created_at":"2025-01-01T12:16:09.373Z","updated_at":"2026-03-02T21:06:31.601Z","avatar_url":"https://github.com/roydejong.png","language":"JavaScript","readme":"# shortcode-tree\nA node.js parser library for reading shortcodes.\n\n[![npm](https://img.shields.io/npm/v/shortcode-tree.svg)](https://www.npmjs.com/package/shortcode-tree)\n[![Build Status](https://travis-ci.org/roydejong/shortcode-tree.svg?branch=master)](https://travis-ci.org/roydejong/shortcode-tree)\n\n## Introduction\n`shortcode-tree` offers generic parsing functionality for text containing short codes (also known as bb codes).\n\nThis library does not convert short codes to HTML (like many other libraries do), but **it converts generic shortcode/HTML input to pure JavaScript objects**.\n\nNo set up is required, and you do not need to pre-define a list of shortcodes.\n\nExample:\n\n    ShortcodeParser.parseShortcode('[image id=123 src=\"bla.jpg\" align=\"center\"/]');\n    \n    // Shortcode {\n    //     name: 'image',\n    //     content: null,\n    //     properties: { id: '123', src: 'bla.jpg', align: 'center' },\n    //     isSelfClosing: true,\n    //     codeText: '[image id=123 src=\"bla.jpg\" align=\"center\"/]',\n    //     offset: 0 }\n\n## Features\n\n- Parse sets of mixed shortcodes and text/HTML into a tree structure\n- Parse individual shortcode fragments\n- Supports self-closing tags\n- Supports tag properties (with or without string literals)\n- Stringify `Shortcode` objects to shortcode text or HTML equivalent\n- Extract only text / HTML from a document containg shortcodes\n\n## Installation\n\nInstallation with `npm`:\n\n    npm install shortcode-tree --save\n    \n## Usage\n\nStart with the raw text you want to process, and feed it to the `parse` function:\n\n    var ShortcodeTree = require('shortcode-tree').ShortcodeTree;\n    \n    var rootNode = ShortcodeTree.parse(inputText);\n    console.log(rootNode.children.length);\n    \nThis function will return a `ShortcodeNode` object. Each `ShortcodeNode` may contain a set of child nodes.\n\nIf you have regular text or HTML mixed in at the same level as a shortcode, a `ShortcodeNode` may also contain `TextNode` children to hold these items. Text nodes themselves cannot hold children, only text.\n\n### The `ShortcodeNode` object\n\nA shortcode node contains the following fields:\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `text` | string | The raw text content (code) of this node. |\n| `shortcode` | `Shortcode` or null | Information about the parsed Shortcode represented by this node. Will be `null` if this is the root node. |\n| `children` | array | List of children. May contain `ShortcodeNode` and `TextNode` items. |\n\n### The `Shortcode` object\n\nA parsed shortcode. Typically available through the `shortcode` field of a shortcode node.\n\n#### Fields\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `name` | string | Tag name |\n| `properties` | object | Key/value object with property values indexed by their name |\n| `content` | string or null | The raw, unparsed content of the tag. May contain HTML and other short codes. `NULL` for self-closing tags. |\n| `isSelfClosing` | bool | Indicates whether this is a self-closing tag without any content. |\n| `codeText` | string | The raw shortcode text, as it was parsed. |\n| `offset` | integer | Offset index, relative to the original input string. |\n\n#### Methods\n\n| Signature | Returns | Description |\n| --- | --- | --- |\n| `stringify()` | string | Formats the data in the `Shortcode` object to shortcode text |\n| `stringifyHtml([string/null] tagName)` | string | Formats the data in the `Shortcode` object to HTML text |\n| `hasProperty([string] key)` | boolean | Gets whether property with name `key` exists. |\n| `getProperty([string] key)` | value or null | Gets value of property with name `key`, or NULL if not set. |\n| `setProperty([string] key, value)` | void | Add or update property with given key and value. |\n| `addChild([Shortcode] shortcode)` | void | Append a `shortcode` item to this shortcode's content using stringify. |\n| `appendContent([string] content)` | void | Append content to the existing content. |  \n\n### The `TextNode` object\n\nA piece of raw text or HTML that was placed on the same level as another shortcode. This is always a child of a shortcode node.\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `text` | string | Raw text or code |\n\n### Dumping tree structure\n\nBy calling `traceTree()` on a node, you can dump a simple visualisation of the parsed tree structure.\n\n    var sampleInput =\n        \"[row]\" +\n            \"[col]\" +\n                \"\u003ch1\u003eMy article\u003c/h1\u003e\" +\n                \"[img src=\\\"image.jpg\\\"/]\" +\n            \"[/col]\" +\n            \"[col]\" +\n                \"\u003cp\u003eJust a boring text sample column\u003c/p\u003e\" +\n            \"[/col]\" +\n        \"[/row]\"\n\n    var rootNode = ShortcodeTree.parse(sampleInput);\n    rootNode.traceTree();\n    \nThe above example would generate the following console output:\n\n    +++++ Root Node +++++\n    [Shortcode Node: row], content: [col]\u003ch1\u003eMy article\u003c/h1\u003e[img src=\"image.jpg\"/][/col][col]\u003cp\u003eJust a boring text sample column\u003c/p\u003e[/col]\n    --- [Shortcode Node: col], content: \u003ch1\u003eMy article\u003c/h1\u003e[img src=\"image.jpg\"/]\n    ------ [Text Node], content: \u003ch1\u003eMy article\u003c/h1\u003e\n    ------ [Shortcode Node: img], content: null\n    --- [Shortcode Node: col], content: \u003cp\u003eJust a boring text sample column\u003c/p\u003e\n\n\n## Advanced usage\n\n### Parsing a single short code fragment\n\nTo parse **one** individual short code, use the `ShortcodeParser`:\n\n    var parser = require('shortcode-tree').ShortcodeParser;\n    \n    var shortcode = parser.parseShortcode(\"[b]example content[/b]\");\n    console.log(shortcode.content); // example content\n    \nThe `parseShortcode` method returns a `Shortcode` object.\n\n### Custom parser options\n\nWhen calling `parseShortcode`, you can add an `options` object as a second argument.\n\n    parser.parseShortcode(\"[b]example content[/b]\", { /** insert options **/ })\n\nThe following options are available:\n\n| Option | Type | Default | Description |\n| --- | --- | --- | --- |\n| `mode` | string | `normal` | Parser mode to operate in. See table below. |\n| `offset` | integer | `0` | Offset from the start of the input string, where parsing should begin. |\n| `throwErrors` | boolean | `true` | If enabled: On shortcode parse error, an `Error` is thrown. If disabled: `false` is returned on parse error. |\n| `precise` | boolean | `false` | If things aren't working as expected, enable this for deep recursive parsing. Reduces performance exponentially. |\n| `selfClosingTags` | array | `[]` | You can specify a list of tags that should always be treated as self-closing. Needed when they don't use the \"[selfcloser/]\" syntax. |\n| `predictSelfClosing` | bool | `true` | If enabled, self-closing tags will be predicted by checking if any closing tags can be found anywhere in the input buffer. Improves stability in most situations, but breaks if your tags are \"sometimes\" self closing. |    \n\nThe default options are defined in `ShortcodeParser.DEFAULT_OPTIONS`.\n\n#### Parser modes\n\n| Constant | Value | Description |\n| --- | --- | --- |\n| `MODE_NORMAL` | `normal` | Parses text into a `Shortcode` object. |\n| `MODE_GET_OPENING_TAG_NAME` | `tag_name` | Halts parsing once the tag name is found, and returns it as a string. |\n\n### Extracting one level of shortcodes from text  \n\nThe `ShortcodeExtractor` is a component that can extract a set of Shortcodes from a single piece of text, without traversing deeper than one level.\n\n    var extractor = require('shortcode-tree').ShortcodeExtractor;\n    \n    var shortcodes = extractor.extractShortcodes(\"Hey, [b]bold[/b] and [i]beautiful[/i].\");\n    console.log(shortcodes);\n    \n    // [ Shortcode {\n    //     name: 'b',\n    //     content: 'bold',\n    //     properties: {},\n    //     isSelfClosing: false,\n    //     codeText: '[b]bold[/b]',\n    //     offset: 5 },\n    //   Shortcode {\n    //     name: 'i',\n    //     content: 'beautiful',\n    //     properties: {},\n    //     isSelfClosing: false,\n    //     codeText: '[i]beautiful[/i]',\n    //     offset: 21 } ]\n\nThe `extractShortcodes` method returns an array of `Shortcode` objects. \n\n### Extracting text/HTML from a shortcode fragment\n    \n    var treeParser = require('shortcode-tree').ShortcodeTree;\n\n    var input = `root [row][column]deep[/column][/row]`;\n    treeParser.extractTextContent(input);\n   \n    // returns: \"root deep\"","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froydejong%2Fshortcode-tree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froydejong%2Fshortcode-tree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froydejong%2Fshortcode-tree/lists"}