Metadata-Version: 2.4
Name: vyasa
Version: 0.6.32
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>

Vyasa turns a folder of Markdown into a navigable site served by Python. It is for people who want notes, docs, books, or a blog to feel like a real site without adding a JavaScript build stack. This README is the shortest path from `pip install vyasa` to a working local site. By the end, you should know how to run it, what it is good at, and which manual page to open next when the simple path stops being enough.

# Vyasa

Vyasa is a lightweight Markdown site engine built on FastHTML. It gives you a live local server, folder-aware navigation, rich Markdown features, CSS-first theming, and a static build path from the same content tree.

## Start Here

```bash
pip install vyasa
mkdir my-notes
cd my-notes
printf '# Hello\n\nThis is my first Vyasa page.\n' > index.md
vyasa .
```

Open `http://127.0.0.1:5001`.

If you want Google login later, install `pip install "vyasa[auth]"`. If you want a static export instead of a live server, run `vyasa build . -o ./dist`.

## The First Configuration Most People Add

```toml
title = "My Notes"
theme_preset = "serene-manuscript"
sidebars_open = true
```

Put that in a `.vyasa` file at the root of your content folder. Configuration precedence is CLI args > `.vyasa` > environment variables > defaults, so you can start simple and still override behavior when you need to.

## What It Buys You

- Write plain Markdown, then opt into Vyasa features like callouts, tabs, Mermaid, D2, math, footnotes as sidenotes, and code snippet includes only when the page needs them.
- Keep content organized as folders; `index.md` or `README.md` becomes the landing page for that branch.
- Use a blog-style homepage at `/` when you want the newest posts first, or set `home_sort = "name_asc"` / `home_sort = "name_desc"` to order homepage cards by filename instead.
- Style the site with normal CSS and bundled theme presets instead of introducing a component system.
- Use the same content tree for a live local server and a static export.
- Add auth and RBAC when the content stops being public or personal.

## Feature Map

```mermaid
mindmap
  root((Vyasa))
    Authoring
      Markdown
      Callouts
      Tabs
      Footnotes as sidenotes
      Math
      Code snippet includes
      Tasks graphs
    Diagrams
      Mermaid
      D2
    Navigation
      Folder-aware tree
      README or index landing pages
      Breadcrumbs and TOC
      Present mode from docs
    Styling
      CSS-first theming
      Theme presets
      Custom CSS hooks
    Runtime
      Live Python server
      HTMX page swaps
      Search and rich page chrome
    Publishing
      Static export
      Blog-style homepage
      Manual, notes, docs, books in one tree
    Access
      Google auth
      RBAC rules
```

## What A Content Tree Looks Like

```text
my-notes/
├── .vyasa
├── index.md
├── posts/
│   ├── first-post.md
│   └── second-post.md
└── manual/
    ├── README.md
    └── architecture.md
```

Folders become navigation groups. `index.md` or `README.md` gives a folder its own landing page, so a blog, a manual, and a notebook can live in the same tree without special routing setup.

## When You Need The Next Layer

If your next question is about shaping the site, open the [configuration guide](vyasa%20manual/configuration.md). If the question is about what the authoring surface can do, go to [Markdown writing features](vyasa%20manual/markdown-features.md). Diagram-specific behavior lives in the [Mermaid guide](vyasa%20manual/mermaid-diagrams.md) and the [D2 guide](vyasa%20manual/d2-diagrams.md), while shell styling and theme presets are covered in [theming](vyasa%20manual/theming.md).

Use [security](vyasa%20manual/security.md) when the site needs login or path rules, [architecture demo](demo/vyasa-architecture-system-design-tasks.md) when you want the request and rendering model in graph form, and [advanced behavior](vyasa%20manual/advanced.md) when you are past the happy path and want the edges. The items/tasks graph surface now supports markdown links inside attr values like `spec: [API](guide#api)`, plus group color inheritance where child nodes use the nearest colored parent group unless they set their own color. Shared palettes can live in one JSON file via `color_palette_source: shared-palettes.json` with `node_color_palettes` and `edge_color_palettes` inside it.

The manual itself starts at [vyasa manual/README.md](vyasa%20manual/README.md), but you should not need it before the quick start above works.
