Markdown-2-HTML

This is a markdown to HTML transpiler - created to learn about how lexical analysis and how ASTs work.

You should consider this a naive implementation, because it's mostly for learning purposes.

To install dependencies:

bun install

To run:

bun run index.ts

How does it work?

The transpiler is a three step process to actually have HTML in the other end of the program.

Lexical analysis

When given markdown, I do a lexical analysis of the input and create tokens based on how the input looks like – character by character.

Example of this is a heading: # This is a title

This would produce a token that looks like this:

{
  type: "heading",
  value: "This is a title",
  attributes: {
    level: 1
  }
}

Parser

The parser's job is to look at the tokens of the lexical analysis and produce a more of a hierarky, and create an abstract syntax tree (AST) that gives you the tree of the program and in what order things should be rendered at.

Example of how the AST looks like given the heading token in the previous section:

{
  type: "Document",
  children: [
    {
      type: "heading",
      tag: "h1",
      children: [
        {
          type: "text",
          tag: "__no_tag__",
          value: "This is a title"
        }
      ]
    }
  ]
}

Generator

The generator's job is to actually produce output code based on the AST. And the more info the AST provides, the easier it gets to generate output. Since the AST also provides a hierarky of children, we can also introduce neat child-parent stuff in our output aswell.

What markdown features the transpiler currently supports?

The transpiler currently supports following features of markdown

| Feature | Is supported | | ----------------- | ------------ | | Headings | ✅ | | Paragraphs | ✅ | | lists | ✅ | | horizontal rulers | ✅ | | blockquotes | ✅ | | links | ✅ | | italic | ✅ | | bold | ✅ | | image | ✅ | | tables | ❌ | | inline code | ❌ | | task list | ❌ | | strikethrough | ❌ |

And probably many other unknown features markdown has that I am not aware of.

API

When installing the transpiler (programmatically only for now - might be an CLI later), you can do the following:

import { markdown2HTML } from "@oyvindher/markdown-2-html";

const simulatedMarkdownInput = `
  # Hello world

  This is a markdown file.

  ## Todos
  - create a transpiler
  - learn about transpilers
  - have fun

  ---

  cya later
`;

const transpiled = markdown2HTML(simulatedMarkdownInput);

transpiled.tokens; // Tokens from the lexical analysis
transpiled.ast; // The complete AST based on the tokens
transpiled.html; // The generated HTML from the AST

Bun

This project was created using bun init in bun v1.2.4. Bun is a fast all-in-one JavaScript runtime.