Skip to content

Custom Multi Line Syntax

theblackswitch edited this page Aug 12, 2026 · 8 revisions

Logo This page will learn you how you can implement your own custom markdown-like multi-line syntax. This implementation is very similar to the Custom Single Line Synax so go take a look there.

To make it easier to understand, we'll use a small example. Let's say we want to implement the syntax

<This is expandable>
| # Heading
| text
| another line

which allows us to write expandable sections that turn into the following html

<details>
  <summary>This is expandable</summary>
  <h1>Heading</h1>
  <p>text<br>another line</p>
</details>

As you can see we'll also allow other parsers to run within our own text.

📄Table of contents

📝Creating the class

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

For example:

class Collapsible extends YAMP.MultilineParser {

}

Ontop of all methods from the SingleLineParser, there is one more method we can override:

  • The (non static) method extend(...any_paramenters). More on that later

🥇Parsing the first line

Now we can start by parsing the first <This is expandable> just like you would do for a SingleLineParser.

That could look like:

class Collapsible extends YAMP.MultilineParser {
  #summary;

  constructor(summary: string) {
    this.#summary = summary;
  }

  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 {
    if(input.charAt(0) !== "<" || input.charAt(input.length - 2 /* the last character is always a newline */) !== ">") return YAMP.Parser.FAIL;

    // remove the < and > from the charmap as they aren't in the output html
    CHAR_MAP.discard_immediately(char_map_line, char_map_idx, 1);
    CHAR_MAP.discard_immediately(char_map_line, char_map_idx + input.length - 2, 1);
    
    // Collect the actual summary text
    let summary = input.splice(1, input.length - 3);

    // Apply inline parsers to the summary text so we can also bold it
    summary = this.parse_inline(summary, CHAR_MAP, char_map_line, char_map_idx + 1, parsers, options);

    return new Collapsible(summary);
  }
}

➕Extending lines

Ontop of the AST nodeobject or YAMP.Parser.FAIL, the parse method of a multiline parser can also return YAMP.Parser.Extend This means that the current line got extended and thus added by the previous node.

We can use this feature to extend all sub-sequent lines below the summary and add them to the Collapsible node object we're already constructing.

For that we have 2 methods:

  • The (non static) extend(...any_arguments). This overridable method will be called on a previous node when the next line tries to extend this node. This function can return false if extending failed or true if extending succeeded
  • The static try_extend(ast, ...any_arguments). This method will try to extend the previous node. If will return trueif extending succeeded andfalseif it failed. You can append any arguments here and they'll be passed to theextend(...any_arguments)`` method.

For our syntax this might look something like:

class Collapsible extends YAMP.MultilineParser {
  #summary: string;
  #lines = [];

  constructor(summary: string) {
    this.#summary = summary;
  }

  extend(line) {
    this.#lines.push(line);
  }

  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 {
    if(input.charAt(0) === "|" && input.charAt(1) === " ") { // check for the `| ` syntax 
      let line = input.slice(2); // Account for the space too
      if(this.try_extend(ast, line)) {
        return YAMP.Parser.Extend;
      }
      return YAMP.Parser.Fail;
    }

    if(input.charAt(0) !== "<" || input.charAt(input.length - 2 /* the last character is always a newline */) !== ">") return YAMP.Parser.FAIL;

    // remove the < and > from the charmap as they aren't in the output html
    CHAR_MAP.discard_immediately(char_map_line, char_map_idx, 1);
    CHAR_MAP.discard_immediately(char_map_line, char_map_idx + input.length - 2, 1);
    
    // Collect the actual summary text
    let summary = input.splice(1, input.length - 3);

    // Apply inline parsers to the summary text so we can also bold it
    summary = this.parse_inline(summary, CHAR_MAP, char_map_line, char_map_idx + 1, parsers, options);

    return new Collapsible(summary);
  }
}

🧩Parsing Single lines

We'd also like to be able to add any other single line syntax inside of our collapsed blocks. This means we'll need to implement a sub-ast inside of our node. Luckly we can use the method

static parse_ast(lines: Array<string>, CHAR_MAP: CharMap, char_map_line: number, char_map_indices: Array<number> | number, parsers: parsers, options: options, allow_self = true): ast {}

Let's break down it's arguments:

  • lines: An array of all lines we'd like to parse
  • CHAR_MAP: a refrence to the main CharMap object
  • char_map_line: the index of the current line in the charmap and is required to make sure you're editing the correct part of the charmap.
  • char_map_indices: This is an array containing the char_map_idx for each line. You can also specify a single number to use for every line. Take a look at Handeling Charmaps for more information.
  • parsers: a list of all enabled parsers
  • options: a refrence to the main options object
  • allow_self: whether to allow parsing our own class within our sub ast. For example block quotes have this set to true since you can put blockquotes inside blockquotes.

As you can see we need to have all lines available before we can start parsing. Luckly we can override the (non static) method finish(). This method gets called after this node cannot be extended anymore (and thus when we have all lines).

class Collapsible extends YAMP.MultilineParser {
  #summary: string;
  #lines = [];
  #ast = [];

  constructor(summary: string) {
    this.#summary = summary;
  }

  extend(line) {
    this.#lines.push(line);
  }

  finish() {
     this.#ast = static parse_ast(this.#lines, CHAR_MAP ??, char_map_line ??, char_map_indices ??, parsers ??, options ??);
  }

  ...

}

As you can see however, we're missing quite a few arguments. The only way to get them is to store them from our parse function so let's do that.

class Collapsible extends YAMP.MultilineParser {
  #summary: string;
  #lines = [];
  #parsers: parsers = [];
  #options: options;
  #ast: ast = [];
  CHAR_MAP: CharMap;
  char_map_indices: array<number> = [];   // The offset introduced by us cutting off the ``| `` syntax
  char_map_line: number;  // The idx of the first line within the charmap

  constructor(summary: string, CHAR_MAP: CharMap, char_map_line: number, parsers: parsers, options: options) {
    this.#summary = summary;
    this.#parsers = parsers;
    this.#options = options;
    this.CHAR_MAP = CHAR_MAP;
    this.char_map_line = char_map_line;
  }

  extend(line, char_map_idx) {
    this.#lines.push(line);
    this.char_map_indices.push(char_map_idx)
  }

  finish() {
     this.#ast = static parse_ast(this.#lines, this.CHAR_MAP, this.char_map_line, this.char_map_indices, this.#parsers, this.#options);
  }
  
  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 {
    if(input.charAt(0) === "|" && input.charAt(1) === " ") { // check for the `| ` syntax 
      let line = input.slice(2); // Account for the space too
      let new_charmap_idx = char_map_idx + 2; // one for the `|` and one for the ` `
      if(this.try_extend(ast, line, new_charmap_idx)) {
        return YAMP.Parser.Extend;
      }
      return YAMP.Parser.Fail;
    }

    ...

    return new Collapsible(summary, CHAR_MAP, char_map_line, parsers, options);
  }
}

⚙️Generating

Nice, we're finally done with parsing. Now lets get that thing generating, shall we?

To get the output of each of our parsed ast nodes, we can just call the generate(options) method on them.

class Collapsible extends YAMP.MultilineParser {
  #summary: string;
  #lines = [];
  #parsers: parsers = [];
  #options: options;
  #ast: ast = [];
  CHAR_MAP: CharMap;
  char_map_idx: number;
  char_map_line: number;

  ...
  
  generate(options) {
    let out = "<details>";
    out += `<summary>${this.#summary}</summary>`;
    for(const ast_node of this.#ast) {
      out+=`${ast_node.generate(options)}`;
    }
    out += "</details>";
    return out;
  }
}

®️Registering escape chars

That'll look like this

class Collapsible extends YAMP.MultilineParser {
  ...

  static register_escape_chars() {
    return "<>|";
  }
}

✅Done!

Voila we're finally done. This is our finished code:

class Collapsible extends YAMP.MultilineParser {
   #summary: string;
  #lines = [];
  #parsers: parsers = [];
  #options: options;
  #ast: ast = [];
  CHAR_MAP: CharMap;
  char_map_indices: array<number> = [];   // The offset introduced by us cutting off the ``| `` syntax
  char_map_line: number;  // The idx of the first line within the charmap

  constructor(summary: string, CHAR_MAP: CharMap, char_map_line: number, parsers: parsers, options: options) {
    this.#summary = summary;
    this.#parsers = parsers;
    this.#options = options;
    this.CHAR_MAP = CHAR_MAP;
    this.char_map_line = char_map_line;
  }

  extend(line, char_map_idx) {
    this.#lines.push(line);
    this.char_map_indices.push(char_map_idx)
  }

  finish() {
     this.#ast = static parse_ast(this.#lines, this.CHAR_MAP, this.char_map_line, this.char_map_indices, this.#parsers, this.#options);
  }
  
  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 {
    if(input.charAt(0) === "|" && input.charAt(1) === " ") { // check for the `| ` syntax 
      let line = input.slice(2); // Account for the space too
      let new_charmap_idx = char_map_idx + 2; // one for the `|` and one for the ` `
      if(this.try_extend(ast, line, new_charmap_idx)) {
        return YAMP.Parser.Extend;
      }
      return YAMP.Parser.Fail;
    }

    if(input.charAt(0) !== "<" || input.charAt(input.length - 2 /* the last character is always a newline */) !== ">") return YAMP.Parser.FAIL;

    // remove the < and > from the charmap as they aren't in the output html
    CHAR_MAP.discard_immediately(char_map_line, char_map_idx, 1);
    CHAR_MAP.discard_immediately(char_map_line, char_map_idx + input.length - 2, 1);
    
    // Collect the actual summary text
    let summary = input.splice(1, input.length - 3);

    // Apply inline parsers to the summary text so we can also bold it
    summary = this.parse_inline(summary, CHAR_MAP, char_map_line, char_map_idx + 1, parsers, options);

    return new Collapsible(summary, CHAR_MAP, char_map_line, parsers, options);
  }

  generate(options) {
    let out = "<details>";
    out += `<summary>${this.#summary}</summary>`;
    for(const ast_node of this.#ast) {
      out+=`${ast_node.generate(options)}`;
    }
    out += "</details>";
    return out;
  }

  static register_escape_chars() {
    return "<>|";
  }
}

Tip

If you'd like more examples, go take a look in the src/syntax folder of this repo. All yamp's syntax (for example the blockquote) is also implemented like this.

Clone this wiki locally