Starting with Astro Paper

Getting a personal blog up and running can be a daunting task, but frameworks like Astro and themes like AstroPaper make it incredibly straightforward. I can’t sing enough praises for how easy AstroPaper is to customize. The documentation is thorough, and almost everything you need is ready right out of the box.

Table of contents

Easy Deployment

One of the best parts is that you don’t even need to go through the official Astro tutorial to get started. You can deploy your site directly through Vercel, which can be linked to a private GitHub repository. This is peak convenience—your code stays private while your site is public. It just works.

MathJax with STIX Fonts

If you’re writing technical content, you’ll need a robust way to render mathematical equations. AstroPaper supports MathJax, but getting it to work with STIX fonts can be a bit tricky. Here is the configuration you’ll need to add to your BaseLayout.astro or a similar layout component.

This setup ensures that MathJax not only uses the correct STIX2 font from a CDN but also re-renders equations correctly during Astro’s view transitions.

<script is:inline>
  window.MathJax = {
    tex: {
      inlineMath: [['$', '$'], ['\\(', '\\)']]
    },
    chtml: {
      // This is CRITICAL for loading the STIX2 font.
      fontURL: '[https://cdn.jsdelivr.net/npm/mathjax-stix2-font@4.0.0-beta.7/chtml/woff](https://cdn.jsdelivr.net/npm/mathjax-stix2-font@4.0.0-beta.7/chtml/woff)'
    },
    // The startup block handles rendering and page transitions
    startup: {
      // This code runs when MathJax is loaded and ready
      ready() {
        // This runs the default startup routine, which will
        // typeset the page on initial load.
        MathJax.startup.defaultReady();

        // After the initial load, we add a listener for
        // Astro's view transitions.
        document.addEventListener('astro:after-swap', () => {
          // This is the crucial part. On every page swap, we
          // manually trigger a full reset and re-render of the new content.
          MathJax.startup.output.clearCache();
          MathJax.typesetClear();
          MathJax.texReset();
          MathJax.typesetPromise();
        });
      }
    }
  };
</script>

<script id="MathJax-script" async
  src="[https://cdn.jsdelivr.net/npm/mathjax-stix2-font@4.0.0-beta.7/tex-mml-chtml-mathjax-stix2.js](https://cdn.jsdelivr.net/npm/mathjax-stix2-font@4.0.0-beta.7/tex-mml-chtml-mathjax-stix2.js)">
</script>src/layouts/BaseLayout.astro

Better Footnotes with Littlefoot

By default, footnotes in markdown often follow print logic, appearing at the very bottom of the page. This can be inconvenient for web reading. A much better solution is to use tooltip-style footnotes.

After some digging, I found a great solution using littlefoot.js. The setup requires adding a script to handle initialization across page loads, as discussed in this GitHub thread.

Here’s the working code to add to your layout file:

<script is:inline
  src="[https://unpkg.com/littlefoot/dist/littlefoot.js](https://unpkg.com/littlefoot/dist/littlefoot.js)"
  type="application/javascript">
</script>
<script is:inline>
  // This function initializes the footnotes
  function initLittlefoot() {
    littlefoot.littlefoot();
  }

  // Use the 'astro:page-load' event to run the function.
  // This fires on the initial page load and on every subsequent page navigation.
  document.addEventListener('astro:page-load', initLittlefoot);
</script>src/layouts/BaseLayout.astro

Customizing Fonts

AstroPaper uses a default font-mono stack, which looks great but might not be what you want for your own site. If you plan to use custom fonts, resist the urge to ask an LLM or to “vibe code” your way through it. The official Astro documentation on fonts is the best resource by far. It provides a clear, step-by-step process that will save you a lot of headaches.