npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@mtcute/markdown-parser

v0.18.0-rc.5

Published

Markdown entities parser for mtcute

Downloads

2,170

Readme

@mtcute/markdown-parser

📖 API Reference

Markdown entities parser for mtcute

NOTE: The syntax implemented here is not compatible with Bot API Markdown, nor MarkdownV2.

Please read Syntax below for a detailed explanation

Features

  • Supports all entities that Telegram supports
  • Supports nested and overlapping entities
  • Supports dedentation
  • Interpolation!

Usage

import { md } from '@mtcute/markdown-parser'

tg.sendText(
    'me',
    md`
        Hello, **me**! Updates from the feed:
        ${await getUpdatesFromFeed()}
    `
)

Syntax

Inline entities

Inline entities are defined by some tag surrounding some text, and processing them simply strips their tag.

Supported entities:

  • Bold, tag is **
  • Italic, tag is __
  • Underline, tag is -- (NON-STANDARD)
  • Strikethrough, tag is ~~
  • Spoiler, tag is || (NON-STANDARD)
  • Code (monospaced font), tag is `
    • Note that escaping text works differently inside code, see below.

Unlike CommonMark, we use the symbol itself and not its count. Thus, using * (asterisk) will always produce bold, and using _ (underscore) will always produce italic.

This eliminates a lot of confusion, like: _bold_bold, **italic**italic

| Code | Result (visual) | Result (as HTML) | |----------------------------------------------|-------------------|------------------------------| | **bold** | bold | <b>bold</b> | | __italic__ | italic | <i>italic</i> | | --underline-- | underline | <u>underline</u> | | ~~strikethrough~~ | ~~strikethrough~~ | <s>strikethrough</s> | | ||spoiler|| | N/A | <spoiler>spoiler</spoiler> | | *whatever* | *whatever* | *whatever* | | _whatever_ | _whatever_ | _whatever_ | | `hello world` | hello world | <code>hello world</code> | | `text` | __text__ | <code>__text__</code> |

Pre

Pre represents a single block of code, optionally with a language.

This entity starts with ``` (triple backtick), optionally followed with language name and a must be followed with a line break, and ends with ``` (triple backtick), optionally preceded with a line break.

| Code | Result (visual) | Result (as HTML) | |--------------------------------------------------------------------|---------------------------|---------------------------------------------------------------------------------------------| | ```hello``` | hello | <pre>hello</pre> | | ```hello``` | hello | <pre>hello</pre> | | ```javascriptconst a = <br>\`\`\`</code></pre> | <code>const a = | <pre language="javascript"> const a = ``</pre> |

Links

Links are parsed exactly the same as standard markdown (except references are not supported).

Defined like this: [Link text](https://example.com).

  • Link text may also contain any formatting, but link cannot contain other links inside (obviously).
  • [ (opening square bracket) inside link text will be treated like a normal character.

A markdown-style link can also be used to define a name mention like this: [Name](tg://user?id=1234567), where 1234567 is the ID of the user you want to mention.

Additionally, a markdown-style link can be used to define a custom emoji like this: [😄](tg://emoji?id=123456), where 123456 is ID of the emoji.

Note: It is up to the client to look up user's input entity by ID. In most cases, you can only use IDs of users that were seen by the client while using given storage.

Alternatively, you can explicitly provide access hash like this: [Name](tg://user?id=1234567&hash=abc, where abc is user's access hash written as a base-16 unsigned integer. Order of the parameters does matter, i.e. tg://user?hash=abc&id=1234567 will not be processed as expected.

| Code | Result (visual) | Result (as HTML) | |------------------------------------|--------------------------------|--------------------------------------------------| | [Google](https://google.com) | Google | <a href="https://google.com">Google</a> | | [__Google__](https://google.com) | Google | <a href="https://google.com"><i>Google</i></a> | | [empty link]() | empty link | empty link | | [empty link] | [empty link] | [empty link] | | [User](tg://user?id=1234567) | N/A | N/A | | [😄](tg://emoji?id=123456) | N/A | N/A |

Nested and overlapping entities

Quite a powerful feature of this parser is the ability to process overlapping entities. Only inline entities (except code) can be overlapped.

Since inline entities are only defined by their tag, and nesting same entities doesn't make sense, you can think of the tags just as start/end markers, and not in terms of nesting.

| Code | Result (visual) | Result (as HTML) | |-------------------------------|---------------------------|----------------------------------------| | **Welcome back, __User__!** | Welcome back, User! | <b>Welcome back, <i>User</i>!</b> | | **bold __and** italic__ | bold and italic | <b>bold <i>and</i></b><i> italic</i> |

Interpolation

Being a tagged template literal, md supports interpolation.

You can interpolate one of the following:

  • string - will not be parsed, and appended to plain text as-is
    • In case you want the string to be parsed, use md as a simple function: md`... ${md('bold')} ...`
  • number - will be converted to string and appended to plain text as-is
  • TextWithEntities or MessageEntity - will add the text and its entities to the output. This is the type returned by md itself:
    const bold = md`**bold**`
    const text = md`Hello, ${bold}!`
  • falsy value (i.e. null, undefined, false) - will be ignored

Because of interpolation, you almost never need to think about escaping anything, since the values are not even parsed as Markdown, and are appended to the output as-is.