Skip to content

Custom Single Line Syntax

theblackswitch edited this page Aug 5, 2026 · 6 revisions

Logo

This page will learn you how you can implement your own custom markdown-like single line syntax.

To make it easier to understand, we'll use a small example. Let's say we want to use the syntax !> to implement a linkable refrence point. For example something like !> important part would turn into <span id="important-part"></span> and we can add #important-part to the url to link to this point.

📄Table of contents

📝Creating the class

To implement your syntax, start by extending the class YAMP.SingleLineParser

For example:

class RefrencePoint extends YAMP.InlineParser {

}

This class has a couple of methods which we can override:

  • The static property static PRIORITY = 10; This is only rarely used to determine the order in which parsers are processed. The default value is 10. Higher values get parsed earlier.
  • The static method static init() {}. This method will run once before parsing starts which can be useful to initialize a static variable for example.
  • The static method static register_escape_chars(): string | null {}. This method may return a string of characters which may be escaped. More on that later.
  • The static method static escape_text(text: string, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, parsers: parsers): string {} Which is used to escape characters inside text using all registered escapable characters. More on that later.
  • The static method static parse_inline(text: string, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, parsers: parsers, options: options): string {}

And lastly the most important method

static parse(line: string, all_lines: Array<string>, line_idx: number, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, ast: ast, parsers: parsers, options: options): parser_fail | parser_extend | ast_node | null {}

Warning

Even though this method has the same name, it's completely different from InlineParser.parse()

This method will be used to implement our actual syntax. It will run for every line inside the provided markdown input. Let's take a look at all available arguments:

  • line: This is the current line in string form
  • all_lines: An array containing all lines fomr the provided markdown input
  • line_idx: the index of the current line inside the all_lines array
  • CHAR_MAP: a refrence to the main char map object. More on that later
  • char_map_line: The index of the line at which the input string is located. More on that later
  • char_map_idx: An offset to the index of the current input string inside the char map. More on that later
  • ast: An array containing all already parsed nodes. Log this to get a better idea of how the internal ast looks.
  • parsers: An array containing all enabled features
  • options: A way to access the options object. You can add any custom keys inside that object.

This method has basically 2 return options. It returns YAMP.Parser.FAIL to indicate that this feature didn't parse correctly as the syntax isn't present in the source markdown.

Clone this wiki locally