TypeScript Tutorial: Creating a Simple Markdown Previewer

Written by

learnmodernjavascript

in

Markdown is a lightweight markup language that allows you to format text using plain text syntax. It’s incredibly popular for its simplicity and readability, making it ideal for writing documentation, blog posts, and more. But what if you want to see how your Markdown looks without having to publish it? This is where a Markdown previewer comes in handy.

Why Build a Markdown Previewer?

As developers, we often work with Markdown files. Whether it’s for README files in our projects, documentation, or even personal notes, the ability to quickly preview Markdown is invaluable. A previewer allows you to see the rendered output in real-time, helping you catch formatting errors and ensuring your content looks exactly as you intend. This tutorial will guide you through creating a simple, yet functional, Markdown previewer using TypeScript, a language that brings type safety and modern features to JavaScript development.

What You’ll Learn

In this tutorial, you’ll learn:

  • How to set up a basic TypeScript project.
  • How to use a Markdown parsing library.
  • How to handle user input and update the preview dynamically.
  • How to structure your code for readability and maintainability.

Prerequisites

Before we begin, you’ll need the following:

  • Basic knowledge of HTML, CSS, and JavaScript.
  • Node.js and npm (or yarn) installed on your system.
  • A code editor (like VS Code) of your choice.

Setting Up the Project

Let’s get started by setting up our project. Open your terminal and create a new directory for your project, then navigate into it:

mkdir markdown-previewer
cd markdown-previewer

Next, initialize a new npm project:

npm init -y

This command creates a package.json file, which will manage our project’s dependencies. Now, let’s install TypeScript and a few other necessary packages:

npm install typescript @types/marked marked

Here’s what each package does:

  • typescript: The TypeScript compiler.
  • @types/marked: Type definitions for the marked library. This is important for type safety.
  • marked: A popular Markdown parser.

After the installation is complete, let’s set up the TypeScript configuration. Run the following command to generate a tsconfig.json file:

npx tsc --init

Open tsconfig.json in your editor. You can customize the compiler options here. For this project, we’ll keep the default settings, but you might want to adjust the target (e.g., to ‘es6’ or ‘esnext’) and module (e.g., to ‘esnext’ or ‘commonjs’) options based on your needs. A common modification is to set "outDir": "./dist" to specify the output directory for the compiled JavaScript files.

Creating the HTML Structure

Now, let’s create the basic HTML structure for our previewer. Create an index.html file in your project directory. This file will contain the layout of our application.

<!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: 0;
            padding: 20px;
            display: flex;
            flex-direction: column;
            height: 100vh;
        }

        textarea, #preview {
            border: 1px solid #ccc;
            padding: 10px;
            margin-bottom: 10px;
            width: 100%;
            box-sizing: border-box;
        }

        textarea {
            height: 200px;
        }

        #preview {
            flex-grow: 1;
            overflow-y: auto;
        }
    </style>
</head>
<body>
    <textarea id="editor" placeholder="Enter Markdown here..."></textarea>
    <div id="preview"></div>
    <script src="./dist/index.js"></script>
</body>
</html>

In this HTML, we have:

  • A textarea with the id “editor” where the user will input their Markdown.
  • A div with the id “preview” where the rendered HTML will be displayed.
  • Basic CSS for styling.
  • A link to our JavaScript file, which we’ll create next. Note the path `./dist/index.js` This is where the compiled JavaScript will be placed.

Writing the TypeScript Code

Now, let’s write the TypeScript code that will handle the Markdown parsing and previewing. Create a file named index.ts in your project directory. This is where our main application logic will reside.

import { marked } from 'marked';

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

// Function to update the preview
const updatePreview = () => {
    if (editor && preview) {
        const markdownText = editor.value;
        const html = marked.parse(markdownText);
        preview.innerHTML = html;
    }
};

// Add an event listener to the editor to update the preview on input
if (editor) {
    editor.addEventListener('input', updatePreview);
}

// Initial render (in case there's content in the editor on page load)
updatePreview();

Let’s break down this code:

  • We import the marked function from the marked library.
  • We get references to the textarea (editor) and the div (preview) elements from the DOM. We use type assertions (as HTMLTextAreaElement and as HTMLDivElement) to tell TypeScript the expected types. This helps with type checking and autocompletion.
  • The updatePreview function does the following:
    • It gets the Markdown text from the editor.
    • It uses marked.parse() to convert the Markdown to HTML.
    • It sets the innerHTML of the preview div to the generated HTML.
  • We add an event listener to the editor. The 'input' event is triggered whenever the user types something in the textarea. When this event happens, the updatePreview function is called.
  • We call updatePreview() once initially, to render any pre-existing content in the editor when the page loads.

Compiling the TypeScript

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

tsc

This command will use the TypeScript compiler (tsc) to compile your index.ts file into a index.js file (and any necessary files based on your tsconfig.json configuration). The compiled JavaScript will be placed in the dist directory (if you set the `outDir` in tsconfig.json).

Running the Previewer

To run your Markdown previewer, you can open the index.html file in your web browser. You can do this by simply double-clicking the file in your file explorer, or by using a local web server.

If you have Python installed, you can use a simple web server with the following command in your terminal, from the project directory:

python -m http.server

Then, open your browser and go to http://localhost:8000 (or the port specified by the server). You should see the textarea and the preview area. As you type Markdown into the textarea, the rendered HTML should appear in the preview area.

Example Usage

Let’s test our previewer with some Markdown. Try entering the following into the editor:

# Hello, Markdown!

This is a paragraph.

*   Item 1
*   Item 2

**This is bold text.**

You should see the corresponding HTML rendered in the preview area:

Hello, Markdown!

This is a paragraph.

  • Item 1
  • Item 2

This is bold text.

Adding More Features

Our Markdown previewer is functional, but we can enhance it with more features. Here are some ideas:

  • Syntax Highlighting: Use a library like Prism.js or highlight.js to add syntax highlighting to code blocks in your Markdown.
  • Toolbar: Add a toolbar with buttons to easily insert Markdown elements (bold, italic, headings, etc.).
  • Live Preview Styling: Use CSS to style the preview area to match your desired look and feel.
  • Error Handling: Implement error handling to gracefully handle invalid Markdown syntax.
  • File Upload: Allow users to upload Markdown files.

Common Mistakes and How to Fix Them

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

  • Incorrect DOM Element Selection: Make sure you’re selecting the correct HTML elements using document.getElementById(). Double-check your element IDs in your HTML.
  • Typos in Markdown Syntax: Markdown is sensitive to syntax. Ensure you’re using the correct Markdown syntax (e.g., correct number of ‘#’ for headings, asterisks for bold/italic).
  • Incorrect Library Import: Make sure you’ve correctly imported the marked library in your TypeScript file.
  • Uncompiled TypeScript: If your previewer isn’t working, make sure you’ve compiled your TypeScript code to JavaScript using tsc. Check your console for any compilation errors.
  • CSS Conflicts: If the styling isn’t what you expect, check for CSS conflicts. Make sure your CSS rules aren’t being overridden by other CSS in your project or in the browser’s default styles. Consider using a CSS reset or a more specific CSS selector.
  • CORS Issues: If you’re trying to load external resources (e.g., images) in your Markdown, you might encounter CORS (Cross-Origin Resource Sharing) issues. Make sure the server hosting the external resources allows cross-origin requests.

Key Takeaways

In this tutorial, we’ve built a simple Markdown previewer using TypeScript. We’ve learned how to set up a TypeScript project, use a Markdown parsing library, handle user input, and update the preview dynamically. This project demonstrates the power of TypeScript for creating type-safe and maintainable front-end applications. You can now use this as a foundation to build more complex Markdown editors or integrate Markdown previewing into other projects.

FAQ

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

  1. How can I add syntax highlighting to my code blocks?

    You can use a library like Prism.js or highlight.js. Import the library and apply it to the code blocks in your preview using JavaScript after parsing the Markdown.

  2. How do I handle different Markdown flavors?

    The marked library supports various Markdown flavors through options. You can configure the parser to handle different syntaxes (e.g., GitHub Flavored Markdown) by passing options to the marked.parse() function.

  3. How can I allow users to upload Markdown files?

    You can add a file input element to your HTML. When the user selects a file, read the file content using the FileReader API, and then update the editor with the file content.

  4. How can I save the user’s Markdown input?

    You can use local storage to save the content of the editor. Use localStorage.setItem("markdown", editor.value) to save the content and editor.value = localStorage.getItem("markdown") || ""; to load it on page load.

  5. What are some good alternatives to the ‘marked’ library?

    Some alternatives to marked include markdown-it, remarkable, and commonmark. Each library has its own strengths and weaknesses, so choose the one that best suits your needs.

Building a Markdown previewer is a great way to improve your front-end development skills and get a better understanding of how TypeScript can be used in real-world projects. It’s a project that combines HTML, CSS, JavaScript, and TypeScript, offering a practical application of these technologies. As you continue to work on it, consider experimenting with more features, refining the styling, and exploring different Markdown parsing libraries to gain a deeper understanding of the possibilities.

More posts