TypeScript: Building a Simple Markdown Previewer

Written by

learnmodernjavascript

in

In the world of web development, understanding and manipulating text is a fundamental skill. Markdown, a lightweight markup language, has become a popular choice for writing content on the web due to its simplicity and readability. Imagine the convenience of instantly seeing how your Markdown text will appear, without having to refresh the page or switch to a separate preview window. This is where a Markdown previewer comes in handy. In this tutorial, we will dive into building a simple yet effective Markdown previewer using TypeScript, a superset of JavaScript that adds static typing. We will explore how to take Markdown input, convert it to HTML, and display it in real-time. This project will not only teach you the basics of Markdown processing and TypeScript, but it will also provide a practical tool you can use for your own projects.

What is Markdown and Why Use It?

Markdown allows you to format text using simple syntax. For example, you can create headings, add bold or italic text, create lists, and insert links and images. It’s designed to be easy to read and write, making it a favorite among writers, bloggers, and developers.

Here are some of the benefits of using Markdown:

  • Simplicity: Markdown syntax is straightforward and easy to learn.
  • Readability: Markdown files are easy to read and understand, even in their raw form.
  • Portability: Markdown files can be converted to HTML and other formats, making them highly portable.
  • Efficiency: Markdown allows you to focus on content rather than complex formatting.

In contrast to HTML, which can quickly become cluttered with tags, Markdown provides a clean and concise way to format text. Here’s a quick comparison:

Markdown:

# This is a heading

This is a paragraph with **bold** and *italic* text.

- Item 1
- Item 2

[Link to Google](https://www.google.com)

HTML (equivalent):

<h1>This is a heading</h1>

<p>This is a paragraph with <strong>bold</strong> and <em>italic</em> text.</p>

<ul>
  <li>Item 1</li>
  <li>Item 2</li>
</ul>

<a href="https://www.google.com">Link to Google</a>

Setting Up Your Project

Before we start coding, we need to set up our project. We’ll use a simple HTML file, a TypeScript file, and a few dependencies. Let’s get started:

  1. Create a Project Directory: Create a new directory for your project (e.g., `markdown-previewer`).
  2. Initialize npm: Open your terminal, navigate to your project directory, and run `npm init -y`. This will create a `package.json` file.
  3. Install Dependencies: We will use `marked` to convert Markdown to HTML. Also, we will use `typescript` and `ts-node` for running our Typescript code. Install them with the following command: 
    npm install marked typescript ts-node --save-dev
  4. Create Files: Create the following files in your project directory:
    • `index.html`: The HTML file for our application.
    • `src/app.ts`: The TypeScript file where we will write our code.
    • `tsconfig.json`: The TypeScript configuration file.

Your project structure should look like this:

markdown-previewer/
├── index.html
├── package.json
├── src/
│   └── app.ts
└── tsconfig.json

Configuring TypeScript

To configure TypeScript, we need to create a `tsconfig.json` file. This file tells the TypeScript compiler how to compile your code. Here’s a basic `tsconfig.json` file:

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

Let’s break down some of the key options:

  • target: Specifies the JavaScript version to compile to (e.g., ES5, ES6, ES2015).
  • module: Specifies the module system to use (e.g., commonjs, esnext).
  • outDir: Specifies the output directory for the compiled JavaScript files.
  • esModuleInterop: Enables interoperability between CommonJS and ES modules.
  • forceConsistentCasingInFileNames: Enforces consistent casing in file names.
  • strict: Enables strict type checking.
  • skipLibCheck: Skips type checking of declaration files.

Writing the HTML

Next, let’s create the HTML file (`index.html`). This file will contain the basic structure of our application: a text area for Markdown input and a div to display the rendered HTML.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Markdown Previewer</title>
    <style>
        body {
            font-family: sans-serif;
            margin: 20px;
        }
        textarea {
            width: 100%;
            height: 200px;
            margin-bottom: 10px;
        }
    </style>
</head>
<body>
    <textarea id="markdownInput" placeholder="Enter Markdown here..."></textarea>
    <div id="preview"></div>
    <script src="dist/app.js"></script>
</body>
</html>

This HTML file includes:

  • A `textarea` element with the id `markdownInput` for the user to enter Markdown.
  • A `div` element with the id `preview` where the rendered HTML will be displayed.
  • A link to the compiled JavaScript file (`dist/app.js`).
  • Basic CSS styling for better readability.

Writing the TypeScript Code

Now, let’s write the TypeScript code (`src/app.ts`) to handle the Markdown conversion and preview.

import { marked } from 'marked';

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

// Function to render Markdown to HTML
function renderMarkdown(): void {
  if (markdownInput && preview) {
    const markdownText = markdownInput.value;
    // Use marked to convert Markdown to HTML
    const html = marked.parse(markdownText);
    // Set the HTML content of the preview div
    preview.innerHTML = html;
  }
}

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

// Initial rendering (optional) - to show something on page load
renderMarkdown();

Let’s break down this code:

  1. Import `marked`: We import the `marked` library, which we installed earlier, to handle the Markdown parsing.
  2. Get HTML Elements: We use `document.getElementById()` to get references to the `textarea` and `div` elements in our HTML file. We use type assertions (`as HTMLTextAreaElement` and `as HTMLDivElement`) to tell TypeScript what type these elements are, which allows for better type checking.
  3. `renderMarkdown()` function: This function does the following:
    • Gets the Markdown text from the `textarea`.
    • Uses `marked.parse()` to convert the Markdown to HTML.
    • Sets the `innerHTML` of the `preview` div to the generated HTML.
  4. Event Listener: We add an event listener to the `textarea`. When the user types or makes changes in the `textarea`, the `renderMarkdown()` function is called, updating the preview in real-time.
  5. Initial Rendering (Optional): We call `renderMarkdown()` once at the end to render the initial content. This is useful if you want to display some default Markdown when the page loads.

Compiling and Running the Application

Now that we have written the code, it’s time to compile and run the application. Here’s how:

  1. Compile TypeScript: Open your terminal, navigate to your project directory, and run the following command to compile your TypeScript code into JavaScript: 
    tsc

    This command uses the TypeScript compiler (`tsc`) to compile the `src/app.ts` file into `dist/app.js` based on the configuration in `tsconfig.json`.

  2. Open `index.html` in a Browser: Open the `index.html` file in your web browser. You should see a text area and a preview area.
  3. Test the Previewer: Type some Markdown in the text area, and you should see the rendered HTML in the preview area in real-time.

Common Mistakes and Solutions

Here are some common mistakes and how to fix them:

  • Incorrect Paths in HTML: Make sure the path to your compiled JavaScript file (`dist/app.js`) in your `index.html` is correct. Double-check the path in the `<script src=”…”>` tag.
  • Missing Dependencies: Ensure that you have installed all the necessary dependencies, including `marked` and `typescript`. Run `npm install` in your project directory to install all the dependencies listed in your `package.json` file.
  • Typo Errors: TypeScript helps prevent these. Ensure that you have correctly referenced your HTML elements using their IDs. Check for typos in your code, especially when using `document.getElementById()`.
  • Incorrect Type Assertions: Make sure you are using the correct type assertions when getting HTML elements (e.g., `as HTMLTextAreaElement`, `as HTMLDivElement`).
  • Compiler Errors: Check the terminal for any compiler errors when running the `tsc` command. These errors will indicate any syntax or type errors in your TypeScript code.

Enhancements and Features

To make your Markdown previewer even better, consider adding these features:

  • Syntax Highlighting: Implement syntax highlighting for code blocks using a library like Prism.js or highlight.js.
  • Toolbar: Add a toolbar with buttons for common Markdown formatting options (bold, italic, headings, etc.).
  • Live Preview Scrolling: Synchronize the scrolling of the Markdown input and the preview area.
  • Error Handling: Implement error handling to gracefully handle invalid Markdown input.
  • Custom Styles: Allow users to customize the styles of the preview area using CSS.
  • Dark Mode: Add a toggle to switch between light and dark themes.

Key Takeaways

In this tutorial, we have covered the following key concepts:

  • Markdown Basics: You learned what Markdown is and how to use its basic syntax.
  • TypeScript Fundamentals: You gained experience with TypeScript, including setting up a project, using type assertions, and working with event listeners.
  • HTML and CSS: You learned how to create a basic HTML structure and style it with CSS.
  • Using Libraries: You learned how to integrate external libraries like `marked` into your project.
  • Real-time Preview: You built a real-time Markdown previewer that updates the preview as you type.

FAQ

Here are some frequently asked questions:

  1. Q: Can I use this previewer in a React or Angular application?

    A: Yes, you can adapt the concepts and code to use in React, Angular, or any other JavaScript framework. You would typically use the framework’s component structure and lifecycle methods to manage the Markdown input and preview rendering.
  2. Q: How can I handle images and other media?

    A: The `marked` library handles images using the standard Markdown syntax. Ensure that the image paths are correct and accessible from your application. You may also need to configure your server to serve the images correctly.
  3. Q: How do I deploy this previewer?

    A: You can deploy the previewer as a static website. You can upload the HTML, CSS, and JavaScript files to a hosting service like Netlify, GitHub Pages, or Vercel.
  4. Q: What are some alternatives to `marked`?

    A: There are several other Markdown parsing libraries available, such as `markdown-it` and `remark`. These libraries offer different features and performance characteristics.

Building a Markdown previewer is an excellent project for both beginners and intermediate developers. It allows you to practice fundamental web development skills, including HTML, CSS, JavaScript, and TypeScript. By understanding the basics of Markdown processing, you can create various useful tools, from simple text editors to more complex content management systems. The real-time preview aspect enhances the user experience, providing instant feedback as users create and format their content. Furthermore, the use of TypeScript adds type safety and improves code maintainability, which are essential for larger projects. This project can be easily extended with more features, offering a solid foundation for further exploration in web development.

More posts