Publishing notebooks with Astro and Quarto

Introduction

This blog started as a way to document research, programming experiments, and practical workflows for sharing technical outputs with both technical and non-technical audiences.

Most of my work is still notebook-centric, but the default rendering of notebooks in repository viewers can make long analyses difficult to navigate. This motivated the transition toward static sites with stronger layout and information architecture.

Notebook to post

The current site treats notebooks as source material, not as pages served directly from a notebook renderer. A notebook lives in the repository, is converted into Markdown during the content build, and then gets rendered inside the Astro site like any other article.

Quarto is still useful in that pipeline, but only as an intermediary step from `.ipynb` to Markdown. The published site is Astro, and the post route belongs to the Astro app rather than to a separate site.

The same rendering step runs locally before `astro dev` and `astro build`, and it also runs inside the GitHub Actions build and deploy workflows. A notebook post therefore ships with the rest of the site rather than through a separate publication path.

Current workflow

1. Write the post as an `.ipynb` notebook under `notebooks/<section>/`.
2. Add front matter in the first Markdown cell, including title, date, categories, author, and preview image.
3. Run `npm run notebooks:render` so the notebook is converted to Markdown and its assets are copied into the Astro app.
4. Review the result with `npm run dev`, then publish it with the normal Astro build and deploy flow.

Conclusion

The goal is simple: keep notebooks close to the analysis, but publish posts through a site that has stronger layout, navigation, and presentation. Future posts will continue to blend code, scientific context, and web-native presentation without depending on the old site stack.