TypeScript Tutorial: Building a Simple Interactive Markdown to HTML Converter

Written by

learnmodernjavascript

in

In the world of web development, we often encounter the need to convert text from one format to another. Markdown, a lightweight markup language, is a popular choice for writing content due to its readability and ease of use. HTML, on the other hand, is the language of the web, used to structure and display content in browsers. Wouldn’t it be useful to have a tool that seamlessly transforms Markdown into HTML, allowing you to quickly format and publish your content? This tutorial will guide you through building a simple, interactive Markdown to HTML converter using TypeScript. We’ll cover the core concepts, provide step-by-step instructions, and help you understand how to implement this useful functionality.

Why Build a Markdown to HTML Converter?

There are several reasons why building a Markdown to HTML converter can be a valuable skill:

  • Content Creation: Markdown is easier to write and read than HTML, making it ideal for creating blog posts, documentation, and other types of content.
  • Web Development: Many content management systems (CMS) and platforms support Markdown, allowing you to write your content in Markdown and then convert it to HTML for display.
  • Learning: Building a converter is a great way to learn about parsing, regular expressions, and the inner workings of web content formatting.

Prerequisites

Before we dive in, make sure you have the following:

  • Node.js and npm (or yarn): You’ll need Node.js and npm (Node Package Manager) or yarn installed on your system to manage project dependencies and run the TypeScript code.
  • A Code Editor: A code editor like Visual Studio Code (VS Code), Sublime Text, or Atom is recommended for writing and editing your code.
  • Basic Understanding of TypeScript: Familiarity with TypeScript syntax, types, and variables is helpful, but this tutorial will provide explanations along the way.

Setting Up the Project

Let’s start by setting up our project. Open your terminal or command prompt and follow these steps:

  1. Create a Project Directory: Create a new directory for your project and navigate into it:
mkdir markdown-converter
cd markdown-converter
  1. Initialize npm: Initialize a new npm project by running the following command. This will create a package.json file.
npm init -y
  1. Install TypeScript: Install TypeScript as a development dependency:
npm install --save-dev typescript
  1. Create a TypeScript Configuration File: Create a tsconfig.json file in your project directory. This file tells the TypeScript compiler how to compile your code. You can generate a basic one using the following command:
npx tsc --init

This will create a tsconfig.json file with default settings. You can customize this file as needed, but for this project, the defaults should work well.

  1. Create Source Directory: Create a directory called src to hold your TypeScript source files.
mkdir src

Now, your project structure should look something like this:

markdown-converter/
├── package.json
├── tsconfig.json
└── src/

Implementing the Markdown to HTML Conversion

Now, let’s write the core logic for our Markdown to HTML converter. Create a file named src/index.ts and add the following code:

// src/index.ts

/**
 * Converts Markdown text to HTML.
 * @param markdown The Markdown text to convert.
 * @returns The HTML representation of the Markdown text.
 */
function markdownToHTML(markdown: string): string {
  let html = markdown;

  // Heading conversion
  html = html.replace(/^# (.*)/gm, '<h1>$1</h1>');
  html = html.replace(/^## (.*)/gm, '<h2>$1</h2>');
  html = html.replace(/^### (.*)/gm, '<h3>$1</h3>');
  html = html.replace(/^#### (.*)/gm, '<h4>$1</h4>');
  html = html.replace(/^##### (.*)/gm, '<h5>$1</h5>');
  html = html.replace(/^###### (.*)/gm, '<h6>$1</h6>');

  // Bold conversion
  html = html.replace(/**(.*?)**/g, '<b>$1</b>');

  // Italic conversion
  html = html.replace(/*(.*?)*/g, '<i>$1</i>');

  // Paragraph conversion
  html = html.replace(/^(.+)/gm, '<p>$1</p>');

  return html;
}

// Example usage
const markdownText = `
# Hello, Markdown!

This is some **bold** text and *italic* text.

## Subheading

This is a paragraph.
`;

const htmlOutput = markdownToHTML(markdownText);
console.log(htmlOutput);

Let’s break down this code:

  • markdownToHTML(markdown: string): string: This function takes a Markdown string as input and returns an HTML string.
  • Regular Expressions: The code uses regular expressions (regex) to find and replace Markdown syntax with corresponding HTML tags.
  • Heading Conversion: The code replaces Markdown heading syntax (#, ##, etc.) with HTML heading tags (<h1>, <h2>, etc.). The ^ character matches the beginning of a line, (.*) captures the content of the heading, and gm flags are used for global (all occurrences) and multiline matching.
  • Bold and Italic Conversion: The code replaces Markdown bold (**text**) and italic (*text*) syntax with HTML bold (<b>) and italic (<i>) tags.
  • Paragraph Conversion: The code replaces any line that is not a heading with a paragraph tag (<p>).
  • Example Usage: The code includes an example of how to use the markdownToHTML function, converting a sample Markdown string to HTML and logging the output to the console.

Running the Code

To run the code, you need to compile the TypeScript code into JavaScript. Open your terminal and run the following command from the root of your project:

tsc

This command will use the tsconfig.json file to compile the TypeScript files in the src directory and generate JavaScript files in the same directory. Then, run the compiled JavaScript file using Node.js:

node src/index.js

You should see the HTML output in your console.

Adding Interactive Elements (Optional)

To make the converter interactive, you can add a user interface (UI) using HTML, CSS, and JavaScript. Here’s a basic example using HTML and JavaScript:

  1. Create an HTML File: Create an HTML file named index.html in the root of your project with the following content:
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Markdown to HTML Converter</title>
    <style>
        body {
            font-family: sans-serif;
            margin: 20px;
        }
        textarea {
            width: 100%;
            height: 200px;
            margin-bottom: 10px;
        }
    </style>
</head>
<body>
    <h1>Markdown to HTML Converter</h1>
    <textarea id="markdownInput" placeholder="Enter Markdown here..."></textarea>
    <div id="htmlOutput"></div>
    <script src="src/index.js"></script>
    <script>
        const markdownInput = document.getElementById('markdownInput');
        const htmlOutput = document.getElementById('htmlOutput');

        markdownInput.addEventListener('input', () => {
            const markdown = markdownInput.value;
            const html = markdownToHTML(markdown);
            htmlOutput.innerHTML = html;
        });
    </script>
</body>
</html>
  1. Modify src/index.ts: To make the markdownToHTML function accessible in the browser, you need to export it. Modify src/index.ts as follows:
// src/index.ts

/**
 * Converts Markdown text to HTML.
 * @param markdown The Markdown text to convert.
 * @returns The HTML representation of the Markdown text.
 */
function markdownToHTML(markdown: string): string {
    let html = markdown;

    // Heading conversion
    html = html.replace(/^# (.*)/gm, '<h1>$1</h1>');
    html = html.replace(/^## (.*)/gm, '<h2>$1</h2>');
    html = html.replace(/^### (.*)/gm, '<h3>$1</h3>');
    html = html.replace(/^#### (.*)/gm, '<h4>$1</h4>');
    html = html.replace(/^##### (.*)/gm, '<h5>$1</h5>');
    html = html.replace(/^###### (.*)/gm, '<h6>$1</h6>');

    // Bold conversion
    html = html.replace(/**(.*?)**/g, '<b>$1</b>');

    // Italic conversion
    html = html.replace(/*(.*?)*/g, '<i>$1</i>');

    // Paragraph conversion
    html = html.replace(/^(.+)/gm, '<p>$1</p>');

    return html;
}

// Export the function so it can be used in the browser
(window as any).markdownToHTML = markdownToHTML;
  1. Recompile: Run tsc again to compile the updated TypeScript code.
  2. Open index.html: Open index.html in your browser. You should see a text area where you can enter Markdown and a div where the converted HTML will be displayed. As you type in the text area, the HTML will update dynamically.

Common Mistakes and How to Fix Them

Here are some common mistakes and how to fix them when building a Markdown to HTML converter:

  • Incorrect Regular Expressions: Regular expressions are the core of the conversion process. Incorrect regex patterns can lead to unexpected results. Use online regex testers (like regex101.com) to test and debug your regex patterns. Make sure to escape special characters correctly.
  • Missing HTML Tags: Ensure that you include all necessary HTML tags in your conversion logic. For example, if you’re converting Markdown headings, you need to include the appropriate <h1>, <h2>, etc., tags.
  • Incorrect Scope of Regex: Using the wrong flags in your regex expressions can cause problems. For example, using the global flag (g) allows the regex to match all occurrences, while the multiline flag (m) allows the ^ and $ anchors to match the beginning and end of each line, respectively.
  • Unescaped Characters: Special characters in Markdown (like *, _, [, ], (, )) need to be escaped properly in your regex patterns if you want to match them literally.
  • Overlapping Patterns: Be careful with overlapping patterns. For example, if you have both bold and italic conversion, make sure the order of your replacements doesn’t cause issues. It’s generally best to handle the more specific patterns first.

Extending the Converter

You can extend the converter to support more Markdown features. Here are some ideas:

  • Links: Implement support for Markdown links ([text](url)).
  • Images: Implement support for Markdown images (![alt text](url)).
  • Lists: Implement support for ordered and unordered lists.
  • Code Blocks: Implement support for code blocks (using backticks or indentation).
  • Tables: Implement support for Markdown tables.

To extend the converter, you’ll need to add more regex replacements to handle the new Markdown syntax. For each feature, identify the Markdown syntax, create a corresponding HTML tag, and write a regex pattern to perform the conversion.

Key Takeaways

  • TypeScript is a great choice for building web tools because of its strong typing and code organization features.
  • Regular expressions are essential for parsing and converting text formats.
  • Building a Markdown to HTML converter can be a fun and educational project.
  • You can extend the converter to support more Markdown features as needed.

FAQ

Here are some frequently asked questions:

  1. Can I use this converter in a production environment?

    The simple converter provided here is a good starting point for learning. For production environments, you might want to consider using a more robust Markdown parsing library, such as marked or markdown-it, which handle more complex Markdown features and are often optimized for performance.

  2. How can I handle nested Markdown syntax?

    Handling nested Markdown syntax (e.g., bold text within an italicized phrase) can be tricky with simple regex replacements. More advanced parsing techniques or libraries are generally required to handle this correctly.

  3. Why is the HTML output not styled?

    The HTML output generated by the converter only includes the HTML structure. You’ll need to add CSS to style the HTML elements and make them visually appealing. You can either add inline styles or link to an external CSS file.

  4. Can I use this converter in a server-side environment?

    Yes, you can use the markdownToHTML function in a server-side environment (e.g., Node.js) to convert Markdown to HTML on the server. Just make sure to install the necessary dependencies and adjust the code as needed for your server-side framework.

In conclusion, creating a Markdown to HTML converter in TypeScript provides a practical and educational experience. You’ve seen how to translate Markdown syntax into corresponding HTML elements, laying the foundation for a more extensive and feature-rich conversion tool. As you add more features to your converter, you’ll gain a deeper understanding of parsing and web content formatting, reinforcing your skills in TypeScript and web development. This is just the beginning of what you can achieve with a little bit of code and a lot of creativity.

More posts