RELEASE IS NOT STABLE, PLEASE WAIT
A basic MDX blog template that uses exported WLJS Notebooks as MDX files with assets, served as blog posts. This showcases how to integrate interactive Jupyter-style notebooks into a static blog setup using Next.js and MDX with minimal JS.
Each notebook is exported to MDX with associated assets (kernel files, original notebooks, attachments), which are served alongside the blog post content.
- 📝 SSG blog posts from exported WLJS Notebooks in MDX format
- 🚀 Interactive notebook content rendered alongside traditional blog post content
- 🧮 LaTeX and admonitions support
- WLJS blocks load lazily, while valid input expressions are shown as code blocks
- Low FCP (First Contentful Paint) and TTI (Time to Interactive) time
- 📦 Automatic asset management for notebook files and attachments (no need to manually place assets in the
publicfolder) - 🏷️ Support for basic post metadata (title, date, author, tags)
- 🔍 Automatic blog post discovery from
content/posts - 🧑🚀 Ready-to-go workflow for publishing the blog on GitHub Pages
.
├── content/
│ └── posts/ # Your notebook posts in .mdx format
│ └──notebook-1/
│ ├── index.mdx # Post in MDX
│ └── attachments/ # Any related assets
├── src/
│ ├── app/
│ │ ├── blog/ # Blog listing and post pages
│ │ ├── page.tsx # Home page
│ │ ├── layout.tsx # Root layout with navigation
│ │ └── globals.css # Root styles
│ ├── components/ # React components
│ ├── lib/
│ │ └── mdx.ts # MDX utilities for reading posts
│ └── styles/
└── public/ # Static assets (managed)
Please visit wljsteam.github.io/web-components-mdx
- Node.js 22+ and npm/yarn/pnpm
- WLJS Notebook 2.9.2+ (only if WLJS features are needed)
- Install dependencies:
npm install- Start the development server:
npm run dev- Edit the repository name in
./next.config.ts- Commit and push
- Edit the relative path in
./next.config.ts- Build and export
npm run exportBlog posts are MDX files stored in the content/posts directory.
Each post can have frontmatter at the top:
---
title: "Your Post Title"
date: "2024-12-25"
description: "A brief description of your post"
author: "Your Name"
tags: ["tag1", "tag2", "tag3"]
---
# Your Post Title
Your content goes here or generated data from WLJS Notebooktitle(required): Post titledate(required): Publication date in YYYY-MM-DD formatdescription(optional): Short description for the post listingauthor(optional): Author nametags(optional): Array of tags for categorization
- Open your notebook with WLJS app
- Click
Shareand chooseMDX(Static or Interactive) - Export to a new folder at
content/posts/asindex.mdx
All assets will be copied automatically.
Notebook interactivity, plots, and 2D/3D graphics are provided by a supporting web component library served as a single-entry JavaScript file loaded via CDN:
https://cdn.jsdelivr.net/gh/WLJSTeam/web-components@latest/src/common/app.js
In this template, it is included in the footer of layout.tsx.
├── src/
│ ├── app/
│ │ ├── layout.tsx # <----------
This web component library is framework-agnostic; therefore, it is not directly integrated into the React ecosystem as a component. Instead, it is loaded as a script that registers a few custom elements required to render the notebook’s interactive building blocks.
By default, the web components are unstyled; you are free to customize them:
├── src/
│ ├── app/
│ │ └── globals.css # <----------
The current styling in this template is designed to avoid major layout shifts during loading. It is important to show meaningful content before WLJS components are fully loaded.
npm run dev- Start the development servernpm run export- Export statics for Github Pages
MIT