TypeScript Tutorial: Building a Simple Web Application for a Markdown Converter

Written by

learnmodernjavascript

in

In the world of web development, the ability to convert Markdown to HTML is a common need. Whether you’re building a blogging platform, a documentation site, or a simple note-taking application, the ability to parse and render Markdown content is invaluable. This tutorial will guide you, step-by-step, on how to build a simple web application using TypeScript that converts Markdown text into its HTML equivalent. We’ll cover everything from setting up your development environment to writing the core conversion logic, ensuring a solid understanding of TypeScript and practical application.

Why Learn Markdown Conversion?

Markdown is a lightweight markup language that allows you to format text using a plain text editor. It’s designed to be easy to read and write, and it’s widely used for creating documentation, README files, and content for the web. Converting Markdown to HTML is essential because web browsers display HTML, not Markdown. By building a Markdown converter, you gain a deeper understanding of:

  • TypeScript Fundamentals: You’ll practice using types, interfaces, and classes, core components of TypeScript.
  • Web Development Concepts: You’ll learn how to handle user input, manipulate the DOM (Document Object Model), and structure a basic web application.
  • Real-World Applications: Markdown conversion is used everywhere, from content management systems to static site generators.

Setting Up Your Development Environment

Before we dive into the code, let’s set up our development environment. We’ll need Node.js and npm (Node Package Manager) installed. If you don’t have them, download and install them from nodejs.org. Once you have Node.js and npm installed, create a new project directory and initialize a new npm project:

mkdir markdown-converter
cd markdown-converter
npm init -y

This will create a package.json file in your project directory. Next, we’ll install TypeScript and a library to help with the Markdown conversion:

npm install typescript marked --save-dev
  • typescript: The TypeScript compiler.
  • marked: A popular Markdown parser.

Now, let’s create a tsconfig.json file to configure the TypeScript compiler. In your project directory, run:

npx tsc --init --rootDir src --outDir dist

This command creates a tsconfig.json file with default settings. We’ll modify a few of these settings to suit our needs:

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}

Here’s what each setting does:

  • target: Specifies the JavaScript version to compile to (es5 is widely compatible).
  • module: Specifies the module system (commonjs is suitable for Node.js).
  • outDir: Specifies the output directory for compiled JavaScript files.
  • rootDir: Specifies the root directory of your TypeScript source files.
  • strict: Enables strict type checking.
  • esModuleInterop: Enables interoperability between CommonJS and ES modules.
  • skipLibCheck: Skips type checking of declaration files.
  • forceConsistentCasingInFileNames: Enforces consistent casing in file names.
  • include: Specifies the files to include in the compilation.

Creating the HTML Structure

Let’s create the basic HTML structure for our application. Create an index.html file in your project’s root directory. This file will contain the input for Markdown and the output for the converted HTML:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Markdown Converter</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <div class="container">
    <h1>Markdown Converter</h1>
    <div class="input-section">
      <label for="markdownInput">Enter Markdown:</label>
      <textarea id="markdownInput" rows="10" cols="50"></textarea>
    </div>
    <div class="output-section">
      <label for="htmlOutput">HTML Output:</label>
      <div id="htmlOutput"></div>
    </div>
  </div>
  <script src="dist/app.js"></script>
</body>
</html>

This HTML provides:

  • A title for the page.
  • A textarea for entering Markdown.
  • A div to display the converted HTML.
  • A link to a stylesheet (style.css) which we’ll create later.
  • A script tag to include our compiled JavaScript (dist/app.js).

Create a simple style.css file in your project’s root directory to style your application:

body {
  font-family: sans-serif;
  margin: 20px;
}

.container {
  display: flex;
  flex-direction: column;
  align-items: center;
}

.input-section, .output-section {
  margin-bottom: 20px;
}

label {
  display: block;
  margin-bottom: 5px;
}

textarea {
  width: 100%;
  padding: 10px;
  border: 1px solid #ccc;
  border-radius: 4px;
}

#htmlOutput {
  border: 1px solid #ccc;
  padding: 10px;
  border-radius: 4px;
  width: 100%;
  min-height: 100px;
}

Writing the TypeScript Code

Now, let’s write the TypeScript code that will handle the Markdown conversion. Create a src directory in your project and a file named app.ts inside it.

// src/app.ts
import { marked } from 'marked';

// Get references to the HTML elements
const markdownInput = document.getElementById('markdownInput') as HTMLTextAreaElement;
const htmlOutput = document.getElementById('htmlOutput') as HTMLDivElement;

// Function to convert Markdown to HTML
function convertMarkdown() {
  if (markdownInput && htmlOutput) {
    const markdownText = markdownInput.value;
    const html = marked.parse(markdownText);
    htmlOutput.innerHTML = html;
  }
}

// Add an event listener to the textarea
if (markdownInput) {
  markdownInput.addEventListener('input', convertMarkdown);
}

Let’s break down this code:

  • import { marked } from 'marked';: Imports the marked library for Markdown parsing.
  • const markdownInput = document.getElementById('markdownInput') as HTMLTextAreaElement;: Gets a reference to the textarea element from the HTML and casts it to HTMLTextAreaElement for type safety.
  • const htmlOutput = document.getElementById('htmlOutput') as HTMLDivElement;: Gets a reference to the output div and casts it to HTMLDivElement.
  • convertMarkdown(): This function takes the Markdown text from the textarea, uses marked.parse() to convert it to HTML, and then sets the HTML content of the output div.
  • markdownInput.addEventListener('input', convertMarkdown);: Adds an event listener to the textarea. Whenever the user types something in the textarea (the ‘input’ event), the convertMarkdown function is called.

Compiling and Running the Application

Now, let’s compile our TypeScript code into JavaScript. Open your terminal and run the following command in your project directory:

tsc

This will use the tsconfig.json configuration to compile the app.ts file into dist/app.js. If you encounter any errors, check your code and the terminal output for clues.

To run the application, simply open the index.html file in your web browser. You should see the Markdown input area, and as you type, the converted HTML will appear in the output area. You can use Markdown syntax like headings (# Heading), bold text (**bold**), italics (*italics*), lists, and links to test the converter.

Advanced Features and Considerations

While the basic converter is functional, we can add some advanced features to make it more user-friendly and robust. Here are a few ideas:

1. Live Preview

Currently, the HTML updates on every keystroke. This provides a live preview as you type.

2. Error Handling

Consider adding error handling to gracefully handle potential issues, such as invalid Markdown input or problems with the marked library. For instance, you could display an error message in the output area if the parsing fails.

function convertMarkdown() {
  if (markdownInput && htmlOutput) {
    const markdownText = markdownInput.value;
    try {
      const html = marked.parse(markdownText);
      htmlOutput.innerHTML = html;
    } catch (error) {
      htmlOutput.innerHTML = '<p class="error">Error parsing Markdown.</p>';
      console.error(error);
    }
  }
}

3. Custom Styles

You can customize the appearance of the converted HTML by adding CSS styles. For example, you might want to style headings, paragraphs, and lists to match the overall design of your website. You can do this by adding CSS rules to your style.css file or by using a CSS framework like Bootstrap.

4. Code Highlighting

If you plan to support code blocks in your Markdown, you might want to add code highlighting. The marked library integrates with code highlighting libraries such as Prism.js or highlight.js.

First, install the library you choose (e.g., Prism.js):

npm install prismjs

Then, import the necessary Prism.js modules and configure marked to use it:

import { marked } from 'marked';
import Prism from 'prismjs';
import 'prismjs/themes/prism.css'; // Import a theme

marked.use({
  renderer: {
    code(code: string, language: string | undefined) {
      if (language) {
        const highlightedCode = Prism.highlight(code, Prism.languages[language], language);
        return `<pre class="language-${language}"><code>${highlightedCode}</code></pre>`;
      } else {
        return `<pre><code>${code}</code></pre>`;
      }
    },
  },
});

In your HTML, you’ll need to link the Prism.js CSS and JavaScript files:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism.min.css" integrity="sha512-tN7Ec6zAFaVqW94J6eDuEcZHYDWGxoW/8e+M5PrKTSw164P9avqf2UuIzs9XdxxG0Q8g9P2Kgu1jVn/s/mQIDA==" crossorigin="anonymous" referrerpolicy="no-referrer" />
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js" integrity="sha512-7Z9J3lV4w4sWn/Kq+Vf+bJ0yFpLh4j/W6Bf9y29v5O8t9c/p1+eD7r6u1z3D6z/d8c5Z9w8J+oW8a/n9f8jQ==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>

5. Sanitization

If you’re accepting user-provided Markdown, it’s crucial to sanitize the output HTML to prevent cross-site scripting (XSS) attacks. Libraries like DOMPurify can help with this.

npm install dompurify
import { marked } from 'marked';
import DOMPurify from 'dompurify';

function convertMarkdown() {
  if (markdownInput && htmlOutput) {
    const markdownText = markdownInput.value;
    const html = marked.parse(markdownText);
    const sanitizedHtml = DOMPurify.sanitize(html);
    htmlOutput.innerHTML = sanitizedHtml;
  }
}

Common Mistakes and How to Fix Them

Here are some common mistakes beginners make when building a Markdown converter and how to avoid them:

  • Incorrect Paths in HTML: Ensure that the paths to your CSS and JavaScript files in the index.html file are correct. Use relative paths (e.g., src/app.js) if the files are in the same directory or adjust the path appropriately.
  • Typos in Element IDs: Double-check the element IDs in your HTML (markdownInput and htmlOutput) and ensure they match the IDs you’re using in your TypeScript code (document.getElementById(...)). Case sensitivity matters!
  • Not Compiling TypeScript: Remember to recompile your TypeScript code (tsc) every time you make changes to the .ts files. Otherwise, your changes won’t be reflected in the browser.
  • Forgetting to Import: Make sure you’ve imported the marked library correctly at the top of your app.ts file: import { marked } from 'marked';.
  • Incorrect Event Listener: Ensure that you’ve added the event listener to the correct element. In our case, it’s the markdownInput textarea.
  • Ignoring Type Errors: Pay close attention to TypeScript’s type errors in your editor or terminal. They can help you catch mistakes early.

Summary / Key Takeaways

In this tutorial, we’ve walked through the process of building a simple Markdown converter using TypeScript. You’ve learned how to set up a development environment, write the necessary HTML and TypeScript code, compile the code, and run the application. You’ve also explored some advanced features, such as error handling, custom styles, code highlighting, and sanitization, to make your converter more robust and user-friendly.

The key takeaways from this tutorial include:

  • Using TypeScript to build a web application.
  • Working with HTML elements and the DOM.
  • Using a Markdown parsing library (marked).
  • Handling user input and output.
  • The importance of error handling and security.

FAQ

Here are some frequently asked questions about building a Markdown converter:

  1. Can I use a different Markdown parser? Yes, there are many Markdown parsing libraries available, such as Showdown. The core concepts of the application would remain the same; you would simply change the import and the function call to parse the Markdown.
  2. How do I deploy this application? You can deploy this application on a web server. You would need to upload the HTML, CSS, and JavaScript files to the server. Consider using a service like Netlify or Vercel for easy deployment.
  3. Can I use this converter in a React or Angular application? Yes, you can. The core logic of the Markdown conversion remains the same. You would integrate the Markdown parsing and HTML output into the component structure of your React or Angular application.
  4. How can I add features like image uploads or tables? The marked library supports various extensions. You can configure the parser to handle features like image uploads, tables, and other Markdown extensions. Consult the marked documentation for details.

Building a Markdown converter is a fantastic way to learn the fundamentals of TypeScript and web development. As you continue to experiment and expand the functionality of your converter, you’ll gain valuable experience and deepen your understanding of these technologies. From here, you can explore more advanced features like handling different Markdown flavors, supporting custom styles, and even integrating with a backend to store and retrieve Markdown content. The possibilities are vast, and with each feature you add, you’ll solidify your skills and build a more complete understanding of web application development.

More posts