Metadata-Version: 2.4
Name: vyasa
Version: 0.4.11
Summary: A lightweight, elegant blogging platform built with FastHTML
Home-page: https://github.com/yeshwanth/vyasa
Author: Yeshwanth
Author-email: 
License: Apache-2.0
Project-URL: Homepage, https://github.com/yeshwanth/vyasa
Project-URL: Repository, https://github.com/yeshwanth/vyasa
Project-URL: Issues, https://github.com/yeshwanth/vyasa/issues
Keywords: fasthtml,blog,markdown,htmx,mermaid,sidenotes
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: FastAPI
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-fasthtml>=0.6.9
Requires-Dist: mistletoe>=1.4.0
Requires-Dist: python-frontmatter>=1.1.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: monsterui>=0.0.37
Requires-Dist: loguru>=0.7.3
Requires-Dist: fastsql>=2.1.2
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Provides-Extra: auth
Requires-Dist: authlib>=1.3.0; extra == "auth"
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

---
title: Vyāsa
---

<p align="center">
  <img src="static/icon.png" alt="Vyāsa icon" class="vyasa-icon" style="width: 256px;">
</p>

<p class="vyasa-caption" style="text-align: center;">
  Markdown feeds Python<br>
  Instant sites, no code juggling<br>
  CSS reigns supreme
</p>


---

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](https://github.com/sizhky/vyasa/blob/fa9a671931ad69b24139ba9d105bbadd8753b85b/custom.css#L36C1-L36C13).<br>
    Check out the [Theming & CSS](vyasa%20manual/theming.md) 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:
   ```bash
   pip install vyasa
   ```

2. Create a directory with your markdown files:
   ```bash
   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:
   ```bash
   vyasa .
   ```

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


## Key Features

### 🚀 Vyāsa at a Glance

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:

```cytograph
---
height: 65vh
layout: vyasa
initial_depth: 1
source: ./vyasa-map.cytree
---
```

### ✨ 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
- **Inline Annotations**: Select text to add margin comments with hover/click bloom highlighting, replies, and author-aware edit/delete controls
- **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](vyasa%20manual/markdown-features.md).

### 🎬 Zen Slides
- **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](/slides/demo/vyasa-slides).

### 🎨 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   | —                             |
| Annotations                 | Content  | `[annotations]`                                  | Text selection comments with margin threads in doc view; disabled in slide view                                | disabled      | `VYASA_ANNOTATIONS_ENABLED`   |
| 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)

```bash
pip install vyasa
```

### From source

```bash
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
1. **[`.vyasa` configuration file](vyasa%20manual/configuration.md)** (TOML format)
2. **Environment variables** - Fallback
3. **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.

| Guide | Docs | Slides |
|---|---|---|
| Configuration & CLI | [Open](vyasa%20manual/configuration.md) | [Present](/slides/vyasa%20manual/configuration/slide-1) |
| Markdown Writing Features | [Open](vyasa%20manual/markdown-features.md) | [Present](/slides/vyasa%20manual/markdown-features/slide-1) |
| Mermaid Diagrams | [Open](vyasa%20manual/mermaid-diagrams.md) | [Present](/slides/vyasa%20manual/mermaid-diagrams/slide-1) |
| D2 Diagrams | [Open](vyasa%20manual/d2-diagrams.md) | [Present](/slides/vyasa%20manual/d2-diagrams/slide-1) |
| Architecture Overview | [Open](vyasa%20manual/architecture.md) | [Present](/slides/vyasa%20manual/architecture/slide-1) |
| Theming & CSS | [Open](vyasa%20manual/theming.md) | [Present](/slides/vyasa%20manual/theming/slide-1) |
| Security & Auth | [Open](vyasa%20manual/security.md) | [Present](/slides/vyasa%20manual/security/slide-1) |
| Advanced Behavior | [Open](vyasa%20manual/advanced.md) | [Present](/slides/vyasa%20manual/advanced/slide-1) |
