I added Latex Support

In 2022, I discovered Obsidian, a fantastic note-taking software that uses markdown as its primary syntax for taking notes. That being said I was also a nuclear technician and engineer in the Navy. I am quite comfortable with LaTeX which has been the standard for writing and compiling scientific papers for decades.

As developers you know that one of the major advantages of using markdown is its readability and simplicity. However, I wanted to extend this flexibility by adding LaTeX support. Obsidian natively supports LaTeX, but how can we achieve the same in Astro.js?

Here’s an example of how to use LaTeX in markdown:

$E=mc^2$ is Einstein's famous equation.

It will be rendered as: $E=mc^2$ is Einstein’s famous equation.

To render LaTeX expressions within Markdown files using dollar sign syntax ($), we need to install a few packages and tweak our Astro configuration file slightly.

Install Packages

We have to install two packages that help with parsing the LaTeX at build-time.

It’s important to understand that these packages will convert your LaTeX to HTML in the same way Astro converts Markdown to HTML.

remark-math This package will be used to detect dollar sign syntax in .md files. Essentially, any LaTeX we want to render will be wrapped in single $ for inline and double $$ for multi-line.

To install run:

npm install remark-math
or
pnpm add remark-math
or
yarn add remark-math

rehype-katex This package actually does the parsing and renders the math LaTeX. Again, at build-time, so our page load time doesn’t suffer.

To install run:

npm install rehype-katex
or
pnpm add rehype-katex
or
yarn add rehype-katex

Tell Astro.js To Use It

Finally, we need to tell Astro that we want it to use these two packages for rendering markdown at build-time. To do this, I simply edited the existing astro.config.ts file to contain the following since this is a generic astro blog template:

import { defineConfig } from "astro/config";
import tailwind from "@astrojs/tailwind";
import react from "@astrojs/react";
import sitemap from "@astrojs/sitemap";
import { SITE } from "./src/config";

// Added for LaTeX support
import remarkMath from "remark-math";
import rehypeKatex from "rehype-katex";

// Other Markdown plugins
import remarkToc from "remark-toc";
import remarkCollapse from "remark-collapse";

// https://astro.build/config
export default defineConfig({
    site: SITE.website,
    integrations: [
        tailwind({
            applyBaseStyles: false,
        }),
        react(),
        sitemap(),
    ],
    markdown: {
        remarkPlugins: [
            remarkMath, // Added for LaTeX support
            remarkToc,
            [
                remarkCollapse,
                {
                    test: "Table of contents",
                },
            ],
        ],
        rehypePlugins: [
            rehypeKatex, // Added for LaTeX support
        ],
        shikiConfig: {
            theme: "one-dark-pro",
            wrap: true,
        },
    },
    vite: {
        optimizeDeps: {
            exclude: ["@resvg/resvg-js"],
        },
    },
    scopedStyleStrategy: "where",
});

Styling Our LaTeX

At this point, if we try to dump our LaTeX into the markdown and view it in the browser, you will notice that it doesn’t look like the LaTeX we were hoping for. Inspecting this element, we can see that it’s a bunch of ‘s.

To get the fancy LaTeX formatting we are want, you must include the katex stylesheet in headers. This stylesheet will know how to style all the ’s generated from the rendering step.

We can paste this somewhere in the of our html. I dropped it inside the Layout.astro component, which is used on all the pages except the about page which has its own layout:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.1/dist/katex.css" integrity="sha384-WsHMgfkABRyG494OmuiNmkAOk8nhO1qE+Y6wns6v+EoNoTNxrWxYpl5ZYWFOLPCM" crossorigin="anonymous">

Note: This will add some overhead to our page load since the stylesheet has to be loaded.

Now you can enjoy the benefits of using both Markdown and LaTeX in your Astro projects! It’s a powerful combination for creating content that looks great and is easy to work with. Happy coding!

This post will be updated here with a breakdown of the new lighthouse scores and will talk about the perfomance trade offs and if they are even significant.