Vyasa

Markdown feeds Python
Instant sites, no code juggling
CSS reigns supreme

Vyasa is a Python-first blogging platform designed to turn your Markdown files into a fully-featured website in seconds. Write your content in clean, simple Markdown—no boilerplate, no configuration hassles—and watch your site come alive instantly. Whether you're a minimalist who wants it just to work or a CSS enthusiast ready to craft pixel-perfect designs, Vyasa adapts to your needs. Start with zero configuration and customize every pixel when you're ready.If you're curious about how the intro was styled, visit this page.

Check out the Theming & CSS guide for details on customizing your blog's appearance.

Quick Start

Install Vyasa:
Copied
pip install vyasa
```
pip install vyasa
```
Create a directory with your markdown files:
Copied
mkdir my-blog cd my-blog echo "# Hello World" > hello.md mkdir -p posts echo "# My First Post\nThis is a sample blog post." > posts/first-post.md
```
mkdir my-blog
cd my-blog
echo "# Hello World" > hello.md
mkdir -p posts
echo "# My First Post\nThis is a sample blog post." > posts/first-post.md
```
Run Vyasa:
Copied
vyasa .
```
vyasa .
```
Open your browser at `http://127.0.0.1:5001`

Key Features

mindmap
  root((🚀 Vyasa Features))
    📝 Markdown
      Footnotes as Sidenotes
      YouTube Embeds
      Task Lists
      Math Notation
      Superscript & Subscript
      Strikethrough
      Relative Links
      Plain-Text Headings
      Pandoc-style Attributes
      Title Abbreviations
      Folder Notes
    🎨 Interactive Elements
      Mermaid Diagrams
        Flowcharts
        Sequence Diagrams
        State Diagrams
        Gantt Charts
      Interactive Diagrams
        Zoom & Pan
        Fullscreen Mode
        Dark Mode Support
        Auto-scaling
      Tabbed Content
      Custom CSS Cascade
     UI/UX
      Responsive Design
      Dark Mode
      Three-Panel Layout
      HTMX Navigation
      Collapsible Folders
      Sidebar Search
      Auto-Generated TOC
      Mobile Menus
      Sticky Navigation
      Active Link Highlighting
      PDF Support
      Copy Button
    ⚙️ Technical
      FastHTML Foundation
      Configuration File Support
      CLI Arguments
      Environment Variables
      Security & Auth
      Advanced Customization

✨ Advanced Markdown Features

Footnotes as Sidenotes: [^1] references become elegant margin notes on desktop, expandable on mobile with smooth animations
YouTube Embeds: Use [yt:VIDEO_ID] or [yt:VIDEO_ID|Caption] for responsive iframe cards with aspect-ratio containers
Task Lists: - [ ] / - [x] render as custom styled checkboxes (green for checked, gray for unchecked) with SVG checkmarks
Mermaid Diagrams: Full support for flowcharts, sequence diagrams, state diagrams, Gantt charts, etc.
Interactive Diagrams:
- Zoom with mouse wheel (zooms towards cursor position)
- Pan by dragging with mouse
- Built-in controls: fullscreen, reset, zoom in/out buttons
- Auto-scaling based on diagram aspect ratio (wide diagrams like Gantt charts get special handling)
- Fullscreen modal viewer with dark mode support
Theme-aware Rendering: Diagrams automatically re-render when switching light/dark mode via MutationObserver
Mermaid Frontmatter: Configure diagram size with YAML frontmatter (width, height, min-height)
Tabbed Content: Create multi-tab sections using :::tabs and ::tab{title="..."} syntax with smooth transitions
Relative Links: Full support for relative markdown links (./file.md, ../other.md) with automatic path resolution
Plain-Text Headings: Inline markdown in headings is stripped for clean display and consistent anchor slugs
Math Notation: KaTeX support for inline $E=mc^2$ and block $$ math equations, auto-renders after HTMX swaps
Superscript & Subscript: Use text for superscript and text for subscript (preprocessed before rendering)
Strikethrough: Use ~~text~~ for strikethrough formatting
Pandoc-style Attributes: Add classes to inline text with `text`{.class #id} syntax for semantic markup (renders as  tags, not <code>)
Cascading Custom CSS: Add custom.css or style.css files at multiple levels (root, folders) with automatic scoping
Title Abbreviations: Configure .vyasa abbreviations to force uppercase acronyms in sidebar and slug-based titles (e.g., ai-features $\to$ AI Features)
Folder Notes: index.md, README.md, or <folder>.md can act as a folder summary; clicking the folder name opens it

See the full list in Markdown Writing Features.

🎨 Modern UI

Responsive Design: Works beautifully on all screen sizes with mobile-first approach
Three-Panel Layout: Posts sidebar, main content, and table of contents for easy navigation
Dark Mode: Automatic theme switching with localStorage persistence and instant visual feedback
HTMX Navigation: Fast, SPA-like navigation without full page reloads using hx-get, hx-target, and hx-push-url
Collapsible Folders: Organize posts in nested directories with chevron indicators and smooth expand/collapse
Sidebar Search: HTMX-powered filename search with results shown below the search bar (tree stays intact)
PDF Posts: PDFs show up in the sidebar and open inline in the main content area
Auto-Generated TOC: Table of contents automatically extracted from headings with scroll-based active highlighting
TOC Autoscroll + Accurate Highlights: Active TOC item stays in view and highlight logic handles duplicate headings
Inline Copy Button: Copy raw markdown from a button placed right next to the post title
Mobile Menus: Slide-in panels for posts and TOC on mobile devices with smooth transitions
Sticky Navigation: Navbar stays at top while scrolling, with mobile menu toggles
Active Link Highlighting: Current post and TOC section highlighted with blue accents
Auto-Reveal in Sidebar: Active post automatically expanded and scrolled into view when opening sidebar
Ultra-Thin Scrollbars: Custom styled 3px scrollbars that adapt to light/dark theme
Frosted Glass Sidebars: Backdrop blur and transparency effects on sidebar components

Feature	Description
FastHTML Integration	Built on FastHTML for high performance and ease of use
Advanced Markdown Support	Footnotes as sidenotes, YouTube embeds, task lists, Mermaid diagrams, math notation, tabbed content, and more
Modern UI	Responsive design, dark mode, three-panel layout, HTMX navigation
Interactive Diagrams	Zoomable, pannable Mermaid diagrams with fullscreen support

Installation

From PyPI (recommended)

Copied

pip install vyasa

From source

Copied

git clone https://github.com/yeshwanth/vyasa.git
cd vyasa
pip install -e .

Configuration

Vyasa supports four ways to configure your blog (in priority order):

cli arguments (e.g. vyasa /path/to/markdown) - Highest priority
.vyasa configuration file (TOML format)
Environment variables - Fallback
Default values - Final fallback

Vyasa Manual

Short, focused guides for deeper topics. Start with configuration and writing content, then dive into architecture and advanced details.