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. (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 StartURL copied

1. Install Vyāsa:

   Copy code

   Copied

   pip install vyasa

   pip install vyasa
   

2. Create a directory with your markdown files:

   Copy code

   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
   

3. Run Vyāsa:

   Copy code

   Copied

   vyasa .

   vyasa .
   

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

Key FeaturesURL copied

🚀 Vyāsa at a GlanceURL copied

Hiding in plain sight, Vyāsa packs a powerful punch of features that transform simple Markdown files into dynamic, interactive websites. From advanced Markdown capabilities to modern UI/UX design and technical robustness, Vyāsa is built to empower creators of all levels. Here's a high-level overview of what Vyāsa brings to the table:

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
      Zen Slides
        Present Mode
        Real Slide URLs
        H2/H3 Structural Splits
        Doc Theme Inheritance
      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 FeaturesURL copied

• 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.

🎬 Zen SlidesURL copied

• One-click Present Mode: Add slides: true in frontmatter and Vyāsa shows a Present button that opens /slides/<path>/slide-1
• Structural Slide Splits: ## starts a horizontal slide and ### plus deeper headings become detail slides under the current section
• Real Slide URLs: Every slide is addressable as /slides/<path>/slide-N, so refresh, copy-link, and open-in-new-tab work like normal pages
• Doc Theme Inheritance: Slide pages reuse the normal doc shell, so fonts, background, theme preset, and custom.css stay aligned with reading view
• HTMX Navigation: Left/right movement uses the same #main-content swap contract as normal Vyāsa navigation instead of a separate deck runtime
• Slides with Existing Vyāsa Features: Mermaid, D2, tabs, code highlighting, math, and long-form sections continue to work in slide view

See the working example in Vyasa Slides Demo.

🎨 Modern UIURL copied

• 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

InstallationURL copied

From PyPI (recommended)URL copied

pip install vyasa

From sourceURL copied

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

ConfigurationURL copied

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 ManualURL copied

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