vyasa 0.3.74

A lightweight, elegant blogging platform built with FastHTML

---

title: Vyāsa

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

---

Vyāsa 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, Vyāsa adapts to your needs. Start with zero configuration and customize every pixel when you're ready.[^1]

[^1]: 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.

[!info] Vyāsa is named after the legendary sage Krishna Dvaipayana Vyāsa, who is credited with compiling the ancient Indian epic - the Mahabharata, 18 puranas and many more spiritually significant works.

Just as Vyāsa organized vast knowledge into a coherent narrative, Vyāsa the blogging platform helps you organize your thoughts and content into a beautiful, functional website with ease.

---

Quick Start

1. Install Vyāsa:

   pip install vyasa
   

2. Create a directory with your markdown files:

   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
   

3. Run Vyāsa:

   vyasa .
   

4. Open your browser at http://127.0.0.1:5001

Key Features

mindmap
  root((🚀 Vyāsa 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
      Reveal.js Slides
        Present Mode
        Horizontal + Vertical Slides
        Frontmatter Config Support
        Theme + Highlight Control
      Mermaid Diagrams
        Flowcharts
        Sequence Diagrams
        State Diagrams
        Gantt Charts
      D2 Diagrams
        Layouts & Themes
        Composition Animation
        Scenario/Layers Support
      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.
• D2 Diagrams: Supports architecture/process diagrams with interactive rendering and composition animation support.
• 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
  • 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 and metadata with YAML frontmatter (width, height, aspect_ratio, title)
• D2 Frontmatter: Configure rendering and animation with YAML frontmatter:
  • width, height, title
  • layout (elk, dagre, etc.; default is elk), theme_id, dark_theme_id, sketch
  • pad, scale
  • target (board/layer target), animate_interval/animate-interval, animate
  • Notes:
    • Composition animation is enabled with animate_interval
    • If animation is enabled and target is omitted, Vyāsa auto-targets all boards (*)
    • If title is provided, it is used for fullscreen modal title and as a small centered caption under the diagram
• Tabbed Content: Create multi-tab sections using :::tabs and ::tab{title="..."} syntax with smooth transitions
• Code Snippet Includes: Embed external source files with {* path ln[1:24] hl[9:11,22] *} and highlight selected source lines
• Rich Callouts: Supports Obsidian-style > [!warning]- Title callouts with aliases, folding, nesting, and CSS-targetable custom types
• 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 <span> 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.

🎬 Reveal.js Slides

• One-click Present Mode: Add slides: true in frontmatter and Vyāsa shows a Present button that opens /slides/<path> in Reveal.js
• Markdown-Native Slide Splits: Use --- for horizontal slides and -- for vertical slides (customizable with separator and separatorVertical)
• Frontmatter Config Support: Set Reveal options via nested reveal: or top-level reveal_* keys; these are passed into Reveal.initialize(...)
• Theme + Highlight Control: Configure theme and highlightTheme for deck appearance and code styling
• Optional Linear Right-Arrow Navigation: Use reveal_rightAdvancesAll: true (or reveal: { rightAdvancesAll: true }) so Right Arrow advances through every slide, including vertical/below slides
• Slides with Existing Vyāsa Features: Mermaid, D2, code highlighting, and math rendering all work inside slides

See the working example in Reveal Slides Demo.

🎨 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
• Theme Presets: Set theme_preset in .vyasa to use a bundled theme like serene-manuscript, kinetic-scholar, or ultra-soft
• Theme Primary Override: Set theme_primary in .vyasa to swap the app accent color without editing CSS

Feature	Category	Config Key	Description	Default	Env Override
FastHTML Integration	Core	—	Built on FastHTML and Starlette for high-performance async rendering without a build step	enabled	—
Advanced Markdown Support	Content	—	Footnotes as sidenotes, YouTube embeds, task lists, Mermaid + D2 diagrams, math notation, tabbed content, and more	enabled	—
Modern UI	UI	sidebars_open, layout_max_width, theme_preset, theme_primary	Responsive three-panel layout with dark mode, HTMX navigation, frosted glass sidebars, configurable width, bundled theme presets, and optional primary override	false, unset, serene-manuscript, forest green	VYASA_SIDEBARS_OPEN, VYASA_THEME_PRESET, VYASA_THEME_PRIMARY
Interactive Diagrams	Content	[drawings_passwords]	Zoomable, pannable Mermaid and D2 diagrams with fullscreen support and optional per-drawing password protection	unprotected	—
Auth & RBAC	Security	[google_oauth], [rbac]	Google OAuth login with allowed domains/emails, role-based access control rules scoped per path	disabled	VYASA_GOOGLE_CLIENT_ID, VYASA_RBAC_ENABLED
Sidebar Navigation	UI	folder_tabs, folders_first, order, sort	Collapsible file tree with tab grouping, custom entry ordering, sort direction, and smart abbreviation expansion	false, name_asc	—
Content Filtering	Config	ignore, include, show_hidden	Fine-grained control over which files and folders appear in listings, with hidden-file visibility toggle	all visible	VYASA_SHOW_HIDDEN
Server Configuration	Config	host, port, title, root	Bind address, deterministic port derived from working directory, site title, and content root path	127.0.0.1	VYASA_HOST, VYASA_PORT

Installation

From PyPI (recommended)

pip install vyasa

From source

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

Configuration

Vyāsa supports four ways to configure your blog (in priority order):

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

Theme presets are bundled with the package, so theme_preset = "ultra-soft" works in normal pip install vyasa deployments without copying a local .vyasa-themes folder. Local .vyasa-themes/<name>.toml files still override bundled presets when present.

Vyāsa Manual

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

• Configuration & CLI
• Markdown Writing Features
• Mermaid Diagrams
• D2 Diagrams
• Architecture Overview
• Theming & CSS
• Security & Auth
• Advanced Behavior