Skip to content

Custom Inline Syntax

theblackswitch edited this page Aug 5, 2026 · 9 revisions

This page will learn you how you can implement your own custom markdown-like 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 line break. For example something like Hello world \ Lorem ipsum would turn into Hello world <br> Lorem ipsum.

📄Table of contents

📝Creating the class

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

For example:

class LineBreak extends YAMP.InlineParser {

}

This class has a couple of methods and properties 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. This is very rarely used within inline parsers but it's available if you'd want.

And lastly the most important method

static parse(input: string, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, options: options): Array<YAMP.InlineModifer> {

}

This method will be used to implement our actual syntax. Let's take a look at all available parameters:

  • input: This is the input markdown string fully unparsed.
  • 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
  • options: A way to access the options object. You can add any custom keys inside that object

Now to implement our syntax, we can't simply return a modified string since then our next parser doesn't have the raw input anymore. This also introduces some problems with aligning characters in the char map. That's why we should return an array of modifiers instead. Don't worry, it's not as complicated as you might think.

⚙️Modifiers

These 3 types of modifiers you can use:

Insert

YAMP.InlineModifier.new_insert(idx: number, value: string);

This modifier is used to insert a piece of text at a certain location inside the input string.

Arguments

  • idx: the index at which we should insert
  • value: the value to insert at

Delete

YAMP.InlineModifier.new_delete(idx: number, count: number, modify_char_map?: boolean);

This modifier is used to remove characters from the input string.

Arguments

  • idx: the index at which we should start deleting the string. (Inclusive)
  • count: the number of characters to delete
  • modify_char_map(optional, defaults to false): whether to modify the charmap according to the change

Replace

YAMP.InlineModifier.new_replace(idx: number, count: number, new_value: string, modify_char_map?: boolean);

This modifier is used to remove characters from the input string and replace them with a new string. There is no need for the strings to match in length.

Warning

It's not a good idea to replace big sections since other inline modifiers can't run within this replaced section!

❌ Don't do YAMP.InlineModifier.new_replace(start_idx, end_idx - start_idx, `<strong>${text}</strong>`)
✅ Instead do YAMP.InlineModifier.new_replace(start_idx, start_length, '<strong>') and YAMP.InlineModifier.new_replace(end_idx - end_length, end_length, '</strong>');

Arguments

  • idx: the index at which we should start deleting the string. (Inclusive)
  • count: the number of characters to delete
  • new_value: the number of characters to delete
  • modify_char_map(optional, defaults to false): whether to modify the charmap according to the change

🧩Implementing the syntax

Okay now we have everyting to properly implement our syntax. Lets start with detecting a \ with spaces before and after

class LineBreak extends YAMP.InlineParser {
  static parse(input: string, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, options: options): Array<YAMP.InlineModifier> {
     for(let i = 0; i < input.length; i++) { // Loop through all characters in the string
        if(input.charAt(i) === "\\" && input.charAt(i - 1) === " " && input.charAt(i + 1) === " ") { // Check for a backslash with spaces before and after
        }
     }
  }
}

Now we can implement the modifiers, for this one it's best to use a replacement modifier

class LineBreak extends YAMP.InlineParser {
  static parse(input: string, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, options: options): Array<YAMP.InlineModifier> {
     let modifiers = [];

     for(let i = 0; i < input.length; i++) { // Loop through all characters in the string
        if(input.charAt(i) === "\\" && input.charAt(i - 1) === " " && input.charAt(i + 1) === " ") { // Check for a backslash with spaces before and after     modifiers.push(YAMP.InlineModifier.new_replace(i - 1, 3, '<br>'));
        }
     }

     return modifiers;
  }
}

🚫Escaping characters

In our syntax we'd also like to be able to just write a normal \ this can be done by allowing the backsash to be escaped so people can write \\ which turns into \.

To register an escape character we can use the static register_escape_chars() {} method you've seen before. This will result in our code looking like this:

class LineBreak extends YAMP.InlineParser {
  static parse(input: string, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, options: options): Array<YAMP.InlineModifier> {
     let modifiers = [];

     for(let i = 0; i < input.length; i++) { // Loop through all characters in the string
        if(input.charAt(i) === "\\" && input.charAt(i - 1) === " " && input.charAt(i + 1) === " ") { // Check for a backslash with spaces before and after     modifiers.push(YAMP.InlineModifier.new_replace(i - 1, 3, '<br>'));
        }
     }

     return modifiers;
  }

  static register_escape_chars() { // Register \ as an escape character
    return "\\";
  }
}

🗺️Char Maps

Now the last thing we have to do is handle the charmap and make sure the three characters \ get removed. This can be done by calling the appropriate methods on the provided CHAR_MAP object. Please refer to Handeling Charmaps for more information. This means our code would look something like this:

class LineBreak extends YAMP.InlineParser {
  static parse(input: string, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, options: options): Array<YAMP.InlineModifier> {
     let modifiers = [];

     for(let i = 0; i < input.length; i++) { // Loop through all characters in the string
        if(input.charAt(i) === "\\" && input.charAt(i - 1) === " " && input.charAt(i + 1) === " ") { // Check for a backslash with spaces before and after     modifiers.push(YAMP.InlineModifier.new_replace(i - 1, 3, '<br>'));
          CHAR_MAP.discard_immediately(char_map_line, char_map_idx + i - 1, 3);
        }
     }

     return modifiers;
  }

  static register_escape_chars() {
    return "\\";
  }
}

Alternatively you can also let the charmap inline modifier handle the charmap. This will discard any characters that will be replaced.

class LineBreak extends YAMP.InlineParser {
  static parse(input: string, CHAR_MAP: CharMap, char_map_line: number, char_map_idx: number, options: options): Array<YAMP.InlineModifier> {
     let modifiers = [];

     for(let i = 0; i < input.length; i++) { // Loop through all characters in the string
        if(input.charAt(i) === "\\" && input.charAt(i - 1) === " " && input.charAt(i + 1) === " ") { // Check for a backslash with spaces before and after
          modifiers.push(YAMP.InlineModifier.new_replace(i - 1, 3, '<br>', true));
        }
     }

     return modifiers;
  }

  static register_escape_chars() {
    return "\\";
  }
}

Clone this wiki locally