Skip to content

Migrate blog from MkDocs to a Jac web app; rework publishing infra and scheduling workflow#25

Merged
marsninja merged 13 commits into
jaseci-labs:mainfrom
Jayanaka-98:new_blog
Jun 3, 2026
Merged

Migrate blog from MkDocs to a Jac web app; rework publishing infra and scheduling workflow#25
marsninja merged 13 commits into
jaseci-labs:mainfrom
Jayanaka-98:new_blog

Conversation

@Jayanaka-98

@Jayanaka-98 Jayanaka-98 commented Jun 1, 2026

Copy link
Copy Markdown
Collaborator

Summary

This PR replaces the MkDocs Material site with a Jac web app and reworks the editorial infrastructure around it — publishing, scheduling, and CI. It's the largest structural change to the repo since launch (~6.7k lines across 42 files).

What changed

1. Site rebuilt as a Jac app (no more MkDocs)

The static MkDocs build is replaced by a Jac Cloud app with a React/Vite client.

  • Backend (main.jac) — walkers parse posts/*.md and author metadata from the content dir and serve them as JSON. draft: true posts are filtered; posts identify by slug: frontmatter, not filename.
  • Routes (pages/) — index, blog/index, blog/posts/[slug], blog/categories/{index,[name]}, blog/authors/[id], blog/archive, blog/search, a shared layout, and a [...notFound] catch-all.
  • Components (components/) — PostBody and RunnableJacBlock (interactive Jac code blocks, ported from the old MkDocs/Pyodide setup).
  • Styling — new styles/typography.css, styles/prose.css, styles/main.css for readability and prose layout.
  • Project config (jac.toml) — serve config, client plugin (Vite/React deps), and the Kubernetes scale plugin for deployment.

The old docs/blog/ content tree is kept as the read-only content source so existing posts keep working.

2. Publish + scheduling workflow rework

Scheduling is now decoupled from merge and driven from a GitHub issue instead of the PR. New maintainer reference: .github/RELEASE_FLOW.md.

  • Post URLs are slug-only and permanent (/blog/posts/<slug>): the app serves an in-page "coming soon" state for an unpublished slug and the full article once live — same link throughout. No placeholder page, no date in the URL.
  • New post-ci-automation.yml — on lint success, opens/updates a scheduling-tracker issue (and a docs-reference issue), and posts one sticky comment on the PR linking both.
  • Editors comment /schedule <ISO8601 UTC> on the tracker issue → scripts/schedule_lib.py writes .schedule.yml on main.
  • Reworked auto-publish.yml — hourly cron flips due posts live (removes draft:, rewrites date: on first publish), closes the tracker issue, and comments the live URL.
  • Updated lint-new-posts.yml and slash-schedule.yml to match the new flow.

3. Test suite + CI

4. Misc

  • New logo/assets, public/ symlink for static serving, updated README.md to describe the Jac app.
  • Removed the accidentally-committed .jac/data/server.db* files and added them to .gitignore.

Notes for reviewers

  • This is a migration PR — the MkDocs site and the Jac app coexist in the tree during the transition; the content under docs/blog/posts/ is unchanged and remains the source of truth.
  • Editorial invariants are preserved: draft: true is still the publish gate, .schedule.yml stays bot-owned via schedule_lib.py, and posts are still keyed by slug:.

- Introduced a new CSS file for prose styles, defining typography for long-form content with appropriate spacing, headings, links, and code formatting.
- Created a typography CSS file to establish a consistent editorial type system using Source Serif for body text, Inter for UI elements, and JetBrains Mono for code.
- Defined CSS variables for font families, font sizes, and line heights to ensure a cohesive design across the application.
@Jayanaka-98 Jayanaka-98 changed the title Enhance blog readability and structure Migrate blog from MkDocs to a Jac web app; rework publishing infra and scheduling workflow Jun 1, 2026
@marsninja
marsninja merged commit 3c9def8 into jaseci-labs:main Jun 3, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants