TypeScript Tutorial: Building a Simple Web-Based Markdown Previewer

Written by

learnmodernjavascript

in

In the world of web development, the ability to display formatted text is crucial. Markdown, a lightweight markup language, simplifies this process, allowing you to write content in a plain text format that’s easily converted to HTML. Imagine creating a blog post, a documentation page, or even a simple note-taking application. Manually writing HTML for every heading, bold text, or list can be tedious and time-consuming. This is where a Markdown previewer comes in handy. It takes your Markdown input and instantly transforms it into a visually appealing HTML output, making content creation a breeze. In this tutorial, we’ll dive into building a simple, yet functional, Markdown previewer using TypeScript, focusing on clarity and practical application for both beginners and intermediate developers.

Why Build a Markdown Previewer?

There are several compelling reasons to build a Markdown previewer:

  • Learning TypeScript: This project provides an excellent opportunity to practice core TypeScript concepts like types, interfaces, and DOM manipulation.
  • Practical Skill: Understanding how to parse and render Markdown is a valuable skill for any front-end developer.
  • Customization: You can tailor your previewer to your specific needs, adding features and styling as you see fit.
  • Understanding of Libraries: You’ll learn how to integrate and use external libraries like a Markdown parser.

By the end of this tutorial, you’ll have a working Markdown previewer that you can use in your projects or expand upon. We’ll cover everything from setting up your development environment to handling user input and displaying the formatted output.

Setting Up Your Development Environment

Before we start coding, let’s set up our development environment. You’ll need:

  • Node.js and npm (or yarn): These are essential for managing project dependencies and running your TypeScript code. You can download them from https://nodejs.org/.
  • A Code Editor: Visual Studio Code (VS Code) is a popular and excellent choice, but you can use any editor you prefer.
  • TypeScript Compiler: We’ll install this as a project dependency.

Let’s create a new project directory and initialize it with npm:

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

This will create a package.json file in your project directory. Now, let’s install TypeScript and a Markdown parser library. We’ll use marked for parsing Markdown. Install them using npm:

npm install typescript marked --save-dev

This command installs TypeScript and the `marked` library as development dependencies. The `–save-dev` flag ensures that these packages are only used during development and not in production. Next, create a `tsconfig.json` file to configure the TypeScript compiler. Run the following command in your terminal:

npx tsc --init

This will generate a `tsconfig.json` file with default settings. You can customize this file to control how TypeScript compiles your code. For this project, we can use the default settings, but it’s good practice to review them. Finally, let’s create our project structure. Create the following files and directories:

  • src/ (directory)
  • src/index.ts (file)
  • public/ (directory)
  • public/index.html (file)

Your project structure should look like this:

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

Writing the HTML

Let’s start by creating the HTML structure for our Markdown previewer. Open public/index.html 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>
    <style>
        body {
            font-family: sans-serif;
            margin: 20px;
        }
        textarea {
            width: 100%;
            height: 200px;
            margin-bottom: 10px;
        }
        .preview {
            border: 1px solid #ccc;
            padding: 10px;
        }
    </style>
</head>
<body>
    <textarea id="markdown-input" placeholder="Enter Markdown here..."></textarea>
    <div class="preview" id="preview"></div>
    <script src="bundle.js"></script>
</body>
</html>

This HTML provides:

  • A textarea element for the user to input Markdown.
  • A div element with the class preview to display the rendered HTML.
  • Basic CSS for styling.
  • A link to bundle.js, which will contain our compiled JavaScript code.

Writing the TypeScript Code

Now, let’s write the TypeScript code to handle user input and render the Markdown. Open src/index.ts and add the following code:

import { marked } from 'marked';

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

// Function to render Markdown
function renderMarkdown(): void {
  if (markdownInput && preview) {
    const markdown = markdownInput.value;
    const html = marked.parse(markdown);
    preview.innerHTML = html;
  }
}

// Add an event listener to the textarea
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:

  • Importing marked: We import the marked library to parse Markdown.
  • Getting Elements: We get references to the textarea and the div element using their IDs. The as HTMLTextAreaElement and as HTMLDivElement are type assertions, telling TypeScript the specific type of the elements. This helps with type checking and code completion.
  • 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.
  • Event Listener: We add an input event listener to the textarea. This means that every time 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 in the textarea when the page loads.

Compiling and Running the Code

Now that we’ve written the code, let’s compile it and run it. First, we need to bundle our TypeScript code into a single JavaScript file. We’ll use a simple bundler like Webpack for this. Install Webpack and its CLI:

npm install webpack webpack-cli --save-dev

Next, create a webpack.config.js file in your project root with the following content:

const path = require('path');

module.exports = {
  entry: './src/index.ts',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'public'),
  },
  module: {
    rules: [
      {
        test: /.ts?$/,
        use: 'ts-loader',
        exclude: /node_modules/,
      },
    ],
  },
  resolve: {
    extensions: ['.ts', '.js'],
  },
  devtool: 'source-map',
};

This Webpack configuration:

  • Specifies src/index.ts as the entry point.
  • Specifies that the output file should be named bundle.js and placed in the public directory.
  • Uses ts-loader to transpile TypeScript files.
  • Includes source maps for easier debugging.

Now, add a build script to your package.json file. Open package.json and add the following line to the "scripts" section:


  "scripts": {
    "build": "webpack",
    "start": "webpack serve --open"
  },

Your package.json‘s script section should now look something like this:


  "scripts": {
    "build": "webpack",
    "start": "webpack serve --open"
  },

Now, run the build command:

npm run build

This will compile your TypeScript code and create a bundle.js file in the public directory. Finally, to run your previewer, execute the following command in your terminal:

npm start

This command will start a development server and automatically open your Markdown previewer in your web browser. You can now type Markdown in the left-hand text area, and the rendered HTML will appear in the preview area on the right.

Common Mistakes and How to Fix Them

Here are some common mistakes and how to fix them:

  • Incorrect File Paths: Double-check your file paths in index.html (for the script) and webpack.config.js (for the entry and output). A common error is a 404 error (file not found) in the browser.
  • Typos: Typos in your code, especially in element IDs (e.g., markdown-input) or variable names, can prevent the code from working. Use your browser’s developer tools (usually opened by pressing F12) to check for errors in the console.
  • Incorrect Import Statements: Ensure that you have correctly imported the `marked` library. If you see an error like “Cannot find module ‘marked’”, make sure you’ve installed it using npm and that the import statement is correct: import { marked } from 'marked';.
  • Webpack Configuration Errors: If you encounter issues with Webpack, carefully review your webpack.config.js file. Common problems include incorrect paths or missing loaders. Check the console output for specific error messages.
  • Type Errors: TypeScript will highlight type errors during compilation. Read the error messages carefully and fix any type mismatches. For instance, make sure you are using type assertions (e.g., as HTMLTextAreaElement) when accessing HTML elements.

Adding Features and Enhancements

Once you have a working Markdown previewer, you can add more features and enhancements:

  • Live Preview: The code we’ve written already has live preview functionality. As you type in the textarea, the preview updates in real time.
  • 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 insert Markdown elements (e.g., bold, italic, headings, links).
  • Custom Styles: Customize the CSS to change the appearance of the rendered HTML.
  • Error Handling: Implement error handling to gracefully handle invalid Markdown or other potential issues.
  • Save/Load Functionality: Add features to save the Markdown content to local storage or a server and load it later.
  • Markdown Extensions: Explore Markdown extensions to support additional features like tables, diagrams, and more.

Key Takeaways

  • TypeScript Fundamentals: This tutorial reinforces your understanding of core TypeScript concepts like types, interfaces (though not explicitly used here, they are good to keep in mind), and event listeners.
  • DOM Manipulation: You’ve learned how to interact with HTML elements using JavaScript and TypeScript.
  • Library Integration: You’ve successfully integrated a third-party library (marked) to achieve a specific functionality.
  • Project Structure: You’ve gained experience in setting up a basic project structure for a web application.
  • Build Process: You’ve learned how to use Webpack to bundle your TypeScript code.

FAQ

  1. Can I use a different Markdown parser? Yes, you can. There are many Markdown parsing libraries available. Just make sure to install and import the library and adjust the marked.parse() call accordingly.
  2. How do I add syntax highlighting? You can use a library like Prism.js or highlight.js. Include the library’s CSS and JavaScript in your HTML. Then, after parsing the Markdown, use the library to highlight the code blocks. For example, using Prism.js, you’d add the appropriate CSS and JS files to your HTML, and then call Prism.highlightAll() after rendering the Markdown.
  3. How can I deploy this to the internet? You can deploy your previewer to a platform like Netlify or Vercel. These platforms automatically build and deploy your web application. You’ll need to commit your code to a Git repository (e.g., GitHub) and connect it to the deployment platform.
  4. Can I add a dark mode? Absolutely! You can add a dark mode by adding a button to toggle a CSS class on the body element. For example, you could add a class called dark-mode to the body and then define CSS styles for both light and dark modes.
  5. Why is my preview not updating? Check the browser’s developer console (usually opened by pressing F12) for any errors. Also, ensure that the input event listener is correctly attached to the textarea and that the renderMarkdown() function is being called. Make sure the file paths are correctly set.

Building this Markdown previewer offers a solid foundation for understanding web development with TypeScript. From the initial setup to the final preview, each step contributes to a deeper understanding of how front-end applications are built. The ability to create a tool like this not only enhances your coding skills but also provides a practical solution for handling formatted text. As you experiment with additional features and enhancements, you’ll find yourself not only building a useful tool but also expanding your knowledge and confidence in web development. Consider the possibilities that open up as you integrate this tool into your workflow, from creating quick notes to crafting detailed documentation. The journey doesn’t end here; it’s a stepping stone toward more complex and exciting projects. The ability to manipulate and render text dynamically is a core skill, and this Markdown previewer is an excellent demonstration of that capability.

More posts