@bscotch/steam-bbcode 0.2.0

package/LICENSE.md

@@ -0,0 +1,29 @@
+# License for the Stitch Monorepo
+
+License information for the content of this git repository. The various packages in this repo are developed by [Butterscotch Shenanigans](https://www.bscotch.net) ("Bscotch").
+
+## License files
+
+Whenever a `LICENSE` file is found in a folder, or a license is specified by a `package.json` or similar manifest file, that license takes precedence for all files in that folder and its subfolders.
+
+This is the root-most `LICENSE` file, and therefore dictates the default licensing in this repository.
+
+## Stitch name and logo
+
+![Stitch Logo](https://img.bscotch.net/fit-in/256x256/logos/stitch.png "The Stitch Logo, copyright and trademark Butterscotch Shenanigans, all rights reserved.")
+
+Stitch™ and its logo are trademarks of Bscotch. Bscotch reserves all rights to Stitch and its logo.
+
+Stitch Logo ©2022 by Bscotch. All rights reserved.
+
+## Other code and content
+
+Everything found in this project, except for the Stitch name and logo as described above or unless otherwise specified by a more proximal LICENSE file, falls under the MIT license (https://opensource.org/license/mit/):
+
+Copyright 2023 Butterscotch Shenanigans
+
+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.

package/README.md

@@ -0,0 +1,145 @@
+# Steam BBCode Generator
+
+[Steam](https://store.steampowered.com/) has been around for a while, and many parts of its content management system still [use legacy BBCode formats](https://steamcommunity.com/comment/ForumTopic/formattinghelp). This tool helps generate Steam-compatible BBCode from Markdown.
+
+Note: currently only supports _pure_ Markdown (embedded HTML is left as-is).
+
+## Features
+
+- Supports most of [Steam's BBCode format](https://steamcommunity.com/comment/ForumTopic/formattinghelp)
+- Leaves YouTube and Steam links as-is, allowing Steam to convert them into widgets.
+
+## Missing Features
+
+- Only the BBCode markup [documented by Steam](https://steamcommunity.com/comment/ForumTopic/formattinghelp) is supported
+- Only supports pure Markdown input, with the exception of `<img>` tags. HTML is left as-is.
+- Does not support tags that have no equivalent in Markdown
+  - ❌ `[spoiler]`
+  - ❌ `[noparse]`
+  - ❌ `[u]`
+- Does not support tag options that don't have standard support in Markdown
+  - ❌ `[quote=author]` (`[quote]` is supported, but there isn't a way to provide an author)
+
+## Usage
+
+```ts
+import { md2bbcode } from '@bscotch/steam-bbcode';
+
+const converted = md2bbcode('# Hello, world!');
+const bbcode = converted.bbcode;
+```
+
+## Example
+
+The following Markdown input:
+
+```md
+# H1 Heading
+
+## H2 Heading
+
+### H3 Heading
+
+Steam only supports h1-h3, the rest should just be bold.
+
+#### H4 Heading
+
+##### H5 Heading
+
+###### H6 Heading
+
+Some **Bold text**
+
+Some _Italic text_
+
+A [Link](https://example.com 'With a title')
+
+Some ~~Strikethrough text~~
+
+- Unordered list item 1
+- Unordered list item 2
+
+1. **Ordered** list item 1
+1. Ordered list item 2
+
+> Blockquote
+
+Some `Inline Code!`!
+
+\`\`\`
+Block Code!
+\`\`\`
+
+![Image](https://example.com/image.jpg)
+
+[![Image](https://example.com/image.jpg)](https://example.com)
+
+---
+
+Plain steam (store.steampowered.com, steamcommunity.com) and youtube links on their own lines should be left as-is since they'll create widgets
+
+https://store.steampowered.com/app/1401730/Crashlands_2/
+
+https://www.youtube.com/watch?v=yR_Opccn1n4
+
+<!-- Image HTML should get converted even though HTML isn't fully supported by this tool -->
+<img src="https://example.com/image.jpg" alt="Image" />
+```
+
+Yields the following BBCode output:
+
+```bbcode
+[h1]H1 Heading[/h1]
+
+[h2]H2 Heading[/h2]
+
+[h3]H3 Heading[/h3]
+
+Steam only supports h1-h3, the rest should just be bold.
+
+[b]H4 Heading[/b]
+
+[b]H5 Heading[/b]
+
+[b]H6 Heading[/b]
+
+Some [b]Bold text[/b]
+
+Some [i]Italic text[/i]
+
+A [url=https://example.com]Link[/url]
+
+Some [strike]Strikethrough text[/strike]
+
+[list]
+  [*] Unordered list item 1
+  [*] Unordered list item 2
+[/list]
+
+[olist]
+  [*] [b]Ordered[/b] list item 1
+  [*] Ordered list item 2
+[/olist]
+
+[quote]Blockquote[/quote]
+
+Some [code]Inline Code![/code]!
+
+[code]
+Block Code!
+[/code]
+
+[img alt="Image"]https://example.com/image.jpg[/img]
+
+[url=https://example.com][img alt="Image"]https://example.com/image.jpg[/img][/url]
+
+[hr][/hr]
+
+Plain steam (store.steampowered.com, steamcommunity.com) and youtube links on their own lines should be left as-is since they'll create widgets
+
+https://store.steampowered.com/app/1401730/Crashlands_2/
+
+https://www.youtube.com/watch?v=yR_Opccn1n4
+
+[img alt="Image"]https://example.com/image.jpg[/img]
+```

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class SteamBbCodeError extends Error {
+    constructor(message: string, asserter?: Function);
+}
+export declare function assert(claim: any, message: string): asserts claim;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ;CAKjD;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAIjE"}

package/dist/errors.js

@@ -0,0 +1,13 @@
+export class SteamBbCodeError extends Error {
+    constructor(message, asserter) {
+        super(message);
+        this.name = 'SteamBbCode';
+        Error.captureStackTrace?.(this, asserter || this.constructor);
+    }
+}
+export function assert(claim, message) {
+    if (!claim) {
+        throw new SteamBbCodeError(message, assert);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC,YAAY,OAAe,EAAE,QAAmB;QAC9C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,KAAK,CAAC,iBAAiB,EAAE,CAAC,IAAI,EAAE,QAAQ,IAAI,IAAI,CAAC,WAAW,CAAC,CAAC;IAChE,CAAC;CACF;AAED,MAAM,UAAU,MAAM,CAAC,KAAU,EAAE,OAAe;IAChD,IAAI,CAAC,KAAK,EAAE;QACV,MAAM,IAAI,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;KAC7C;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Convert Markdown (or HTML) to Steam-compatible BBCode. Also returns the HTML content.
+ */
+export declare function md2bbcode(source: string): {
+    source: string;
+    bbcode: string;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoFA;;GAEG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAEhB,CAMA"}

package/dist/index.js

@@ -0,0 +1,99 @@
+import { Marked } from 'marked';
+const marked = new Marked({
+    renderer: {
+        heading(src) {
+            // Steam only supports h1-h3, the rest should just be bold.
+            const text = this.parser.parseInline(src.tokens);
+            if (src.depth <= 3) {
+                return `[h${src.depth}]${text}[/h${src.depth}]\n\n`;
+            }
+            else {
+                return `[b]${text}[/b]\n\n`;
+            }
+        },
+        image(src) {
+            return bbImage(src.href, src.text);
+        },
+        link(src) {
+            return `[url=${src.href}]${this.parser.parseInline(src.tokens)}[/url]`;
+        },
+        em(src) {
+            return `[i]${this.parser.parseInline(src.tokens)}[/i]`;
+        },
+        strong(src) {
+            return `[b]${this.parser.parseInline(src.tokens)}[/b]`;
+        },
+        del(src) {
+            return `[strike]${this.parser.parseInline(src.tokens)}[/strike]`;
+        },
+        codespan(src) {
+            return `[code]${src.text}[/code]`;
+        },
+        code(src) {
+            return `[code]\n${src.text}\n[/code]\n\n`;
+        },
+        paragraph(src) {
+            // For lines that are just URLs,
+            // if they are steam or youtube links, leave them as-is
+            if (src.tokens.length === 1 &&
+                src.tokens[0].type === 'link' &&
+                src.tokens[0].raw.match(/^(https?:\/\/)(www\.)?(store\.steampowered\.com|steamcommunity\.com|youtube\.com|youtu\.be)/)) {
+                return src.tokens[0].raw + '\n\n';
+            }
+            return this.parser.parseInline(src.tokens) + '\n\n';
+        },
+        listitem(src) {
+            return ` [*] ${this.parser.parseInline(src.tokens).trim()}`;
+        },
+        list(src) {
+            const el = src.ordered ? 'olist' : 'list';
+            let indent = '  ';
+            let rendered = `[${el}]\n`;
+            for (const item of src.items) {
+                rendered += `${indent}[*] ${this.parser.parseInline(item.tokens).trim()}\n`;
+            }
+            return `${rendered}[/${el}]\n\n`;
+        },
+        hr() {
+            return '[hr][/hr]\n\n';
+        },
+        br() {
+            return '\n\n';
+        },
+        blockquote(src) {
+            return `[quote]${this.parser.parse(src.tokens).trim()}[/quote]\n\n`;
+        },
+        html(src) {
+            if (src.raw.startsWith('<img')) {
+                const alt = src.raw.match(/alt="([^"]+)"/)?.[1] || '';
+                const source = src.raw.match(/src="([^"]+)"/)?.[1] || '';
+                return bbImage(source, alt);
+            }
+            else if (src.raw.startsWith('<!-')) {
+                // Remove HTML comments
+                return '';
+            }
+            // Otherwise return as-is for manual editing
+            return src.text;
+        },
+    },
+});
+/**
+ * Convert Markdown (or HTML) to Steam-compatible BBCode. Also returns the HTML content.
+ */
+export function md2bbcode(source) {
+    const bbcode = marked.parse(source).replaceAll('&#39;', "'");
+    return {
+        source,
+        bbcode,
+    };
+}
+function bbImage(src, alt) {
+    let bb = '[img';
+    if (alt) {
+        bb += ` alt="${alt.replaceAll('"', '&quot;')}"`;
+    }
+    bb += `]${src}[/img]`;
+    return bb;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/dist/index.test.js

@@ -0,0 +1,14 @@
+import { expect } from 'chai';
+import fs from 'node:fs';
+import { md2bbcode } from './index.js';
+/** Sample Markdown containing all kinds of Steam-compatible components */
+const sample = fs.readFileSync('samples/input.md', 'utf-8');
+const expectedSampleBbcode = fs.readFileSync('samples/output.bbcode', 'utf-8');
+describe('BBCode generator', () => {
+    it('should convert Markdown to BBCode', () => {
+        const converted = md2bbcode(sample).bbcode;
+        // fs.writeFileSync('samples/output.bbcode', converted);
+        expect(expectedSampleBbcode).to.equal(converted);
+    });
+});
+//# sourceMappingURL=index.test.js.map

package/dist/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAC9B,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,0EAA0E;AAC1E,MAAM,MAAM,GAAG,EAAE,CAAC,YAAY,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;AAC5D,MAAM,oBAAoB,GAAG,EAAE,CAAC,YAAY,CAAC,uBAAuB,EAAE,OAAO,CAAC,CAAC;AAE/E,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;IAChC,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC;QAC3C,wDAAwD;QACxD,MAAM,CAAC,oBAAoB,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@bscotch/steam-bbcode",
+  "version": "0.2.0",
+  "description": "Generate Steam-compatible BBCode from Markdown.",
+  "homepage": "https://github.com/bscotch/stitch/tree/develop/packages/steam-bbcode#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bscotch/stitch.git",
+    "directory": "packages/steam-bbcode"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "marked": "14.1.2"
+  },
+  "devDependencies": {
+    "chai": "^4.3.10",
+    "mocha": "^10.2.0",
+    "prettier": "^3.1.0",
+    "typescript": "5.2.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "test": "mocha --config ../../config/.mocharc.cjs --parallel=false --timeout=30000",
+    "test:dev": "mocha --config ../../config/.mocharc.cjs --forbid-only=false --parallel=false --timeout=9999999999 --bail=false",
+    "watch": "tsc --build --watch"
+  }
+}