title: Vyāsa
Markdown feeds Python
Instant sites, no code juggling
CSS reigns supreme
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
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
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.mdorREADME.mdbecomes the landing page for that branch. - Use a blog-style homepage at
/when you want the newest posts first, or sethome_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
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
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. If the question is about what the authoring surface can do, go to Markdown writing features. Diagram-specific behavior lives in the Mermaid guide and the D2 guide, while shell styling and theme presets are covered in theming.
Use security when the site needs login or path rules, architecture demo when you want the request and rendering model in graph form, and advanced behavior 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, but you should not need it before the quick start above works.
1 maintainer
Release files for vyasa 0.6.116
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| vyasa-0.6.116.tar.gz | 3.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| vyasa-0.6.116-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 7.7 MB
Release files / vyasa-0.6.116.tar.gz
| Download URL | vyasa-0.6.116.tar.gz |
|---|---|
| Size | 3.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1eb635a2ee95d605865b6a1d4215f2f86219741f225b89d4be45c470088b8d32
|
|
BLAKE2b-256 checksum How to use checksums |
6d057145a9a0fb412f46759c2fa69395e9cfadb13912888689f451fc027484e5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.10
|
Release files / vyasa-0.6.116-py3-none-any.whl
| Download URL | vyasa-0.6.116-py3-none-any.whl |
|---|---|
| Size | 3.8 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c341f0ab7cea336360e277bf68f6d4b90f356d84eb48ccac99cd9c77c827bd2e
|
|
BLAKE2b-256 checksum How to use checksums |
bc2da4b1ffad34f14f8ebf7cd52f622d52a0af75cfc3908b1c7985b22766bf99
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.10
|
