A clean MkDocs blog setup with Jac syntax highlighting and interactive, runnable Jac code blocks.
We welcome contributions from anyone in the community! If you'd like to write a blog post, we'd love to hear from you. Topics can include anything relevant to:
- Jac & Jaseci -- tutorials, tips, deep dives, project showcases
- AI & Machine Learning -- techniques, tools, research, opinions
- Cool Open Source Tools -- discoveries, comparisons, how-tos
- Open Source News -- notable releases, ecosystem updates, community happenings
- Anything Nerdy -- if it's insightful, creative, or just plain fun for a technical audience, we're interested
We'll review all submissions and happily accept anything that's insightful or otherwise enjoyable to the community. Don't be shy -- submit a PR!
- Fork the repo and create a new branch
- Add your post as a markdown file in
docs/blog/posts/:touch docs/blog/posts/my-awesome-post.md
- Add frontmatter to the top of your post:
--- date: 2026-03-12 authors: - your_author_id categories: - Your Category slug: my-awesome-post ---
- Write your post in markdown (see Adding Jac Code Blocks for interactive code examples). We also love Mermaid diagrams -- use
```mermaidcode blocks to add flowcharts, sequence diagrams, and more. For custom graphics, we prefer SVGs since they scale nicely and keep the site looking crisp - If you need images (e.g., screenshots of what you built), place them in
docs/assets/and keep file sizes reasonable -- aim for under 100KB per image when possible. Compress PNGs/JPGs before committing - Open a pull request
If you're a new contributor, add yourself to docs/blog/.authors.yml:
authors:
# ... existing authors ...
your_author_id:
name: Your Name
description: A short bio about yourself
avatar: https://avatars.githubusercontent.com/u/YOUR_GITHUB_USER_ID?v=4To get your GitHub avatar URL, just replace YOUR_GITHUB_USER_ID with your numeric GitHub user ID. You can find your ID by visiting https://api.github.com/users/YOUR_GITHUB_USERNAME -- look for the id field in the response. This will make your profile picture show up nicely alongside your posts.
- Jac Syntax Highlighting: Beautiful syntax highlighting for Jac code using custom Pygments and Monaco lexers
- Interactive Code Blocks: Run Jac code directly in the browser using Pyodide (WebAssembly)
- Clean Design: Built with MkDocs Material theme
- Easy to Use: Simple markdown-based content creation
- Fast: Static site generation for optimal performance
- Python 3.8 or higher
- pip (Python package installer)
- Git
-
Clone this repository (if you haven't already):
cd ~/blog
-
Install all dependencies and the Jac syntax highlighter:
pip install -e .This will install all required dependencies (mkdocs-material, pymdown-extensions, pygments, mkdocs-video, starlette, uvicorn) and register the Jac syntax highlighter.
To start the development server with interactive code execution:
python scripts/mkdocs_serve.pyThis will start a server at http://127.0.0.1:8000 with the necessary CORS headers for Pyodide to work.
Note: The custom server (
mkdocs_serve.py) is required for runnable code blocks to work properly because it sets up the CORS headers needed for SharedArrayBuffer support.
Alternatively, for basic preview without runnable code blocks:
mkdocs serveTo build the static site:
mkdocs buildThe built site will be in the site/ directory.
Deploy to GitHub Pages:
mkdocs gh-deploy-
Create a new markdown file in
docs/posts/:touch docs/posts/my-new-post.md
-
Add the post to the navigation in
mkdocs.yml:nav: - Posts: - My New Post: posts/my-new-post.md
For code that just needs syntax highlighting:
```jac
with entry {
print("Hello, World!");
}
```For code that users can edit and run in the browser:
<div class="code-block">
```jac
with entry {
print("Hello, World!");
}
```
</div>This will add a "Run" button that executes the code in the browser.
You can customize the buttons shown:
- Run only (default):
<div class="code-block"> - Run and Serve:
<div class="code-block run-serve"> - Serve only:
<div class="code-block serve-only">
Example:
<div class="code-block run-serve">
```jac
with entry {
print("This has both Run and Serve buttons!");
}
```
</div>~/blog/
├── docs/ # Documentation source files
│ ├── index.md # Homepage
│ ├── about.md # About page
│ ├── posts/ # Blog posts
│ │ └── welcome.md # Example post
│ ├── js/ # JavaScript files
│ │ ├── jac.monarch.js # Monaco Editor Jac syntax
│ │ ├── run-code.js # Interactive code execution
│ │ └── pyodide-worker.js # Pyodide web worker
│ ├── playground/ # Playground resources
│ │ ├── language-configuration.json
│ │ └── jaclang.zip # (Generated by build hook)
│ ├── extra.css # Custom CSS styling
│ └── assets/ # Images and other assets
├── scripts/ # Build and serve scripts
│ ├── handle_jac_compile_data.py # Build hook for Jac compiler
│ └── mkdocs_serve.py # Custom dev server
├── overrides/ # Theme overrides (optional)
├── jac_syntax_highlighter.py # Pygments lexer for Jac
├── mkdocs.yml # MkDocs configuration
└── README.md # This file
The blog uses two lexers for syntax highlighting:
- Pygments Lexer (
jac_syntax_highlighter.py): Used for server-side static code highlighting during build - Monaco Monarch Lexer (
docs/js/jac.monarch.js): Used for client-side syntax highlighting in the interactive code editor
The runnable code blocks use:
- Pyodide: A Python runtime compiled to WebAssembly that runs in the browser
- Monaco Editor: The same code editor that powers VS Code
- Web Workers: For isolated code execution without blocking the UI
- SharedArrayBuffer: For synchronous input handling (requires special CORS headers)
When you click "Run":
- The code is loaded into Monaco Editor
- A web worker initializes Pyodide and loads the Jac compiler
- The code is executed in the browser
- Output is streamed back to the page in real-time
Edit the palette section in mkdocs.yml:
theme:
palette:
scheme: slate # Use 'default' for light mode
primary: black # Primary color
accent: orange # Accent colorEdit the extra.social section in mkdocs.yml:
extra:
social:
- icon: fontawesome/brands/github
link: https://github.com/yourusername
- icon: fontawesome/brands/twitter
link: https://twitter.com/yourusernameAdd your custom styles to docs/extra.css.
- Make sure you're using the custom server:
python scripts/mkdocs_serve.py - The custom server sets CORS headers required for SharedArrayBuffer
- Check browser console for errors
- Ensure
jac_syntax_highlighter.pyis installed properly - Try rebuilding:
mkdocs build --clean
- Make sure you have the Jac compiler installed
- The hook tries to create
docs/playground/jaclang.zipfrom your Jac installation - If you don't have Jac installed, comment out the hook in
mkdocs.yml
Core dependencies:
mkdocs-material: Material theme for MkDocspymdown-extensions: Markdown extensions for code highlightingpygments: Syntax highlighting librarystarlette: ASGI framework for custom serveruvicorn: ASGI server
Optional dependencies:
mkdocs-video: Video embedding support
[Add your license here]
- Built with MkDocs and Material for MkDocs
- Interactive code execution powered by Pyodide
- Code editor powered by Monaco Editor
- Based on the excellent documentation setup from the Jaseci project
