TypeScript Tutorial: Creating A Simple Web-Based Markdown Previewer

Markdown is a lightweight markup language with plain text formatting syntax. It’s incredibly popular for its simplicity and readability, making it a favorite for writing documentation, README files, and even blog posts. But what if you want to see how your Markdown looks without having to publish it? That’s where a Markdown previewer comes in handy. In this tutorial, we’ll build a simple web-based Markdown previewer using TypeScript, providing a hands-on learning experience for beginners and intermediate developers alike.

Why Build a Markdown Previewer?

Creating a Markdown previewer is an excellent project for several reasons:

Practical Application: You’ll learn how to convert Markdown text into HTML, a skill applicable to many web development tasks.
Understanding of Libraries: You’ll gain experience using external libraries to handle complex tasks, such as Markdown parsing.
Front-End Fundamentals: You’ll reinforce your understanding of HTML, CSS, and JavaScript (with TypeScript).
Problem-Solving: You’ll encounter and solve real-world problems related to text processing and user interface design.

This project will not only teach you the basics of TypeScript but also provide a solid foundation for more advanced front-end development concepts.

Prerequisites

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

Node.js and npm: Used for managing project dependencies and running the development server. You can download them from nodejs.org.
A Code Editor: Such as Visual Studio Code, Sublime Text, or Atom.
Basic HTML, CSS, and JavaScript knowledge: Familiarity with these technologies is helpful, but not strictly required.

Setting Up the Project

Let’s start by setting up our project directory and initializing it with npm. Open your terminal or command prompt and run the following commands:

mkdir markdown-previewer
cd markdown-previewer
npm init -y

This will create a new directory called markdown-previewer, navigate into it, and initialize a package.json file with default settings. Now, let’s install TypeScript and a Markdown parsing library:

npm install typescript marked --save-dev

We’re installing typescript as a development dependency and marked, a popular Markdown parser, as a project dependency. The --save-dev flag ensures that TypeScript is only used during development and not in the production build.

Next, let’s set up the TypeScript configuration file. Create a file named tsconfig.json in the root directory of your project with the following content:

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

This configuration tells the TypeScript compiler to:

Compile to ES5 JavaScript (target: "es5").
Use CommonJS module format (module: "commonjs").
Output the compiled JavaScript files into a dist directory (outDir: "./dist").
Look for TypeScript files in the src directory (rootDir: "./src").
Enable strict type checking (strict: true).
Enable ES module interop (esModuleInterop: true).
Skip type checking of declaration files (skipLibCheck: true).
Enforce consistent casing in file names (forceConsistentCasingInFileNames: true).

Finally, create the src directory and a file named index.ts inside it. This is where we’ll write our TypeScript code.

mkdir src
touch src/index.ts

Building the HTML Structure

Let’s create the basic HTML structure for our Markdown previewer. Create an index.html file in the root directory and add the following code:

<!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>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <div class="container">
        <textarea id="markdown-input" placeholder="Enter Markdown here..."></textarea>
        <div id="preview"></div>
    </div>
    <script src="dist/index.js"></script>
</body>
</html>

This HTML sets up the basic layout:

A textarea with the ID markdown-input for the user to enter Markdown text.
A div with the ID preview where the rendered HTML will be displayed.
A link to a style.css file for styling.
A script tag that includes the compiled JavaScript file (dist/index.js).

Next, create a style.css file in the root directory and add some basic styling to make the previewer look presentable:

body {
    font-family: sans-serif;
    margin: 0;
    padding: 0;
    background-color: #f4f4f4;
    display: flex;
    justify-content: center;
    align-items: center;
    min-height: 100vh;
}

.container {
    display: flex;
    width: 80%;
    max-width: 900px;
    background-color: #fff;
    box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
    border-radius: 8px;
    overflow: hidden;
}

textarea {
    width: 50%;
    height: 600px;
    padding: 20px;
    border: none;
    resize: none;
    font-size: 16px;
    outline: none;
}

#preview {
    width: 50%;
    padding: 20px;
    border-left: 1px solid #ccc;
    font-size: 16px;
    overflow-y: auto;
}

/* Optional: Style Markdown elements */
h1, h2, h3, h4, h5, h6 {
    margin-bottom: 0.5em;
}

p {
    margin-bottom: 1em;
}

code {
    background-color: #eee;
    padding: 2px 4px;
    border-radius: 3px;
    font-family: monospace;
}

pre {
    background-color: #eee;
    padding: 10px;
    border-radius: 5px;
    overflow-x: auto;
}

This CSS provides a basic layout and styling for the textarea and preview area, making the previewer more user-friendly.

Writing the TypeScript Code

Now, let’s write the TypeScript code that will handle the Markdown parsing and preview generation. Open src/index.ts and add the following code:

import { marked } from 'marked';

// Get references to the textarea and preview div
const markdownInput = document.getElementById('markdown-input') as HTMLTextAreaElement;
const preview = document.getElementById('preview') as HTMLDivElement;

// Function to render Markdown to HTML
const renderMarkdown = () => {
  if (markdownInput && preview) {
    const markdownText = markdownInput.value;
    const html = marked.parse(markdownText);
    preview.innerHTML = html;
  }
};

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

// Initial render (in case there's any default text in the textarea)
renderMarkdown();

Let’s break down this code:

Import marked: We import the marked function from the marked library. This function will be used to convert Markdown text into HTML.
Get elements: We get references to the textarea and the preview div using their IDs. The as HTMLTextAreaElement and as HTMLDivElement are type assertions to tell TypeScript the expected types of the elements.
renderMarkdown function: This function does the following:

Gets the Markdown text from the textarea.
Uses marked.parse() to convert the Markdown text to HTML.
Sets the innerHTML of the preview div to the generated HTML.

Event listener: We add an input event listener to the textarea. This means that whenever the user types something in the textarea, the renderMarkdown function will be called, updating the preview.
Initial render: We call renderMarkdown() initially to render any default text that might be present in the textarea when the page loads.

Compiling and Running the Application

Now that we have our TypeScript code, let’s compile it and run the application. In your terminal, run the following command:

tsc

This command will use the TypeScript compiler (tsc) to compile your .ts files into .js files, placing the output in the dist directory as configured in tsconfig.json.

To run the application, you can simply open the index.html file in your web browser. You should see a textarea on the left and an empty area on the right. As you type Markdown in the textarea, the rendered HTML will appear in the preview area.

Common Mistakes and How to Fix Them

Here are some common mistakes and how to fix them:

Incorrect File Paths: Ensure that the paths to your CSS and JavaScript files in index.html are correct. Double-check for typos.
Missing Dependencies: Make sure you’ve installed both typescript and marked using npm.
Type Errors: TypeScript can help you catch errors early. If you see type errors in your code, carefully review the error messages. They often provide valuable clues. For example, if you see an error like “Object is possibly ‘null’”, you might need to add checks like if (markdownInput) { ... }.
Incorrect Element IDs: Make sure the element IDs in your TypeScript code (e.g., markdown-input, preview) match the IDs in your index.html file.
Markdown Rendering Issues: If your Markdown isn’t rendering correctly, double-check your Markdown syntax and make sure the marked library is correctly configured.

Enhancements and Further Learning

Here are some ways you can enhance your Markdown previewer and expand your knowledge:

Add a Toolbar: Implement a toolbar with buttons to insert Markdown syntax (e.g., bold, italic, headings).
Implement Live Preview: Update the preview in real-time as the user types, without waiting for an input event.
Add Syntax Highlighting: Use a library like Prism.js or highlight.js to add syntax highlighting to code blocks in your Markdown.
Implement a Theme Switcher: Allow users to choose between light and dark themes for the preview.
Add Error Handling: Implement error handling to gracefully handle invalid Markdown or unexpected behavior.
Explore Advanced Markdown Features: Learn about tables, footnotes, and other advanced Markdown features and support them in your previewer.
Learn about Webpack or Parcel: For more complex projects, consider using a module bundler like Webpack or Parcel to manage dependencies and optimize your code for production.

Key Takeaways

In this tutorial, you’ve successfully built a simple web-based Markdown previewer using TypeScript. You’ve learned how to:

Set up a TypeScript project.
Use an external library (marked) to parse Markdown.
Interact with HTML elements using TypeScript.
Handle user input with event listeners.
Structure a basic front-end application.

This project provides a solid foundation for understanding front-end development with TypeScript and using external libraries. You can now adapt this knowledge to build more complex applications.

FAQ

Here are some frequently asked questions:

What is Markdown? Markdown is a lightweight markup language that allows you to format plain text using a simple syntax.
What is TypeScript? TypeScript is a superset of JavaScript that adds static typing. It helps you write more maintainable and scalable code.
Why use a Markdown previewer? A Markdown previewer allows you to see how your Markdown text will look when rendered as HTML, without having to publish it.
Can I use a different Markdown parser? Yes, you can use any Markdown parser library that you prefer. marked is a popular choice, but others are available.
How can I deploy this previewer? You can deploy your previewer to a platform like Netlify, Vercel, or GitHub Pages. These platforms offer free hosting for static websites.

Building a Markdown previewer is a fantastic learning experience, offering insights into front-end development, TypeScript, and the power of external libraries. By following this tutorial, you’ve not only created a useful tool but also strengthened your understanding of web development fundamentals. The ability to parse and display Markdown is a valuable skill in many web-related projects, from documentation to blogging. With the skills you’ve gained, the possibilities for expanding and customizing your previewer are endless, allowing you to tailor it to your specific needs and further enhance your development skills. Embrace the opportunity to experiment, learn, and refine your creation, solidifying your understanding and expanding your capabilities in the ever-evolving world of web development.

TypeScript Tutorial: Creating a Simple Web-Based Markdown Previewer

Why Build a Markdown Previewer?

Prerequisites

Setting Up the Project

Building the HTML Structure

Writing the TypeScript Code

Compiling and Running the Application

Common Mistakes and How to Fix Them

Enhancements and Further Learning

Key Takeaways

FAQ

More posts

TypeScript Tutorial: Building a Simple Interactive Drawing Application

TypeScript Tutorial: Building a Simple Interactive Form with Validation

TypeScript Tutorial: Building a Simple Game of Tic-Tac-Toe

TypeScript Tutorial: Building a Simple Currency Converter