Metadata-Version: 2.4
Name: oriel
Version: 0.1.0
Summary: Turn any folder of Markdown into a beautiful website — instantly.
Project-URL: Homepage, https://github.com/jw-y/oriel
Project-URL: Source, https://github.com/jw-y/oriel
Project-URL: Issues, https://github.com/jw-y/oriel/issues
Author-email: Jungwoo Yang <jwyang0213@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Jungwoo Yang
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: docs,figures,markdown,obsidian,server,static-site,viewer
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Python: >=3.11
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: mdit-py-plugins>=0.4
Requires-Dist: pygments>=2.17
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# oriel

**Turn any folder of Markdown into a beautiful website — instantly.**

[![CI](https://github.com/jw-y/oriel/actions/workflows/ci.yml/badge.svg)](https://github.com/jw-y/oriel/actions/workflows/ci.yml)
![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
![License: MIT](https://img.shields.io/badge/license-MIT-green)

<p align="center"><img src="media/hero.png" alt="oriel rendering a folder of agent output as a live site — nav, prose, KaTeX math, and an inline figure" width="820"></p>

```bash
pip install oriel
oriel serve .        # live site → http://127.0.0.1:18787
oriel build .        # or freeze to ./dist to publish
```

Every Markdown file becomes a page, images become a gallery, and edits refresh the browser on their own. It looks like a *publication*, not a file listing — with **no build step, no front matter, no config.**

> [!TIP]
> **Especially good for what agents leave behind.** Point oriel at a folder Claude Code or a research run just wrote and read it as a real site — dated notes, plots, `\(…\)` math and all — instead of scrolling raw files. → [`examples/agent-run`](examples/agent-run)

## Why not MkDocs / markserv / GitHub?

| | **oriel** | MkDocs · Quarto | markserv | GitHub |
|---|:---:|:---:|:---:|:---:|
| No build, no config | ✅ | ❌ | ✅ | ✅ |
| Live on every refresh | ✅ | ~ | ✅ | ❌ |
| Looks like a publication | ✅ | ✅ | ❌ | ~ |
| Figures wall + dashboards | ✅ | ~ | ❌ | ❌ |
| Obsidian `[[wikilinks]]` | ✅ | ❌ | ❌ | ❌ |
| One `pip install`, static export | ✅ | ✅ | ❌ | — |

oriel is the middle that was missing: **a tiny read-only server you keep running next to a folder.**

## What you get

**📂 Any folder → a site.** Loose Markdown at the top level *and* subfolders both show up; a root `README.md` is the home page; images become a gallery. Obsidian vaults and agent dumps work as-is.

**✍️ Real Markdown.** Syntax-highlighted code with copy buttons, KaTeX math in `$…$` *or* `\(…\)`, tables, an auto table-of-contents, and GitHub-style `> [!NOTE]` callouts.

**🔗 Obsidian & agent-native.** `[[wikilinks]]` / `![[embeds]]` resolve, dated notes (`YYYY-MM-DD_*.md`) become a browsable journal, generated plots collect into a **figures wall**.

**⚡ Live & self-contained.** Edits auto-refresh the browser — no manual reload; KaTeX is cached locally so math works offline; light/dark themes with a toggle and six presets.

**📊 Dashboards via plugins.** Drop in an `oriel_plugins.py` for custom pages — the bundled example adds **run-manifest** and **LLM-spend** dashboards.

**🚀 Publish anytime.** `oriel build` freezes everything to static HTML — figures and KaTeX bundled, **search still works** (client-side index) — ready for GitHub Pages.

## Publish (static export)

```bash
oriel build .                    # → ./dist, ready to deploy
oriel build docs --base /oriel   # subpath hosting (e.g. project GitHub Pages)
```

URLs stay identical, math renders offline (bundled KaTeX), and search keeps working via a client-side index. A `.nojekyll` ships for GitHub Pages.

## Configure (optional)

Zero config works. To customize, drop an `oriel.toml` at the folder root:

```toml
title   = "My Notes"
preset  = "ocean"          # terracotta · newsprint · forest · ocean · plum · rose
landing = "guide/intro.md"
```

…or pick a look from the CLI: `oriel serve . --theme forest`. Every key is in [`examples/oriel.toml`](examples/oriel.toml) and the [docs](docs/reference/configuration.md).

## Plugins

A plugin is a `register(site)` function that adds pages:

```python
def register(site):
    @site.page("/status", "status")
    def status():                       # return an HTML body; oriel adds the chrome
        return site.markdown((site.root / "STATUS.md").read_text())
```

See [`examples/oriel_plugins.py`](examples/oriel_plugins.py) for a real one.

> [!WARNING]
> A plugin is ordinary Python that oriel executes — same trust level as running the repo. Don't point oriel at a folder you don't trust.

## Security

oriel is a **read-only** viewer with a shared-secret key — for a personal machine, an SSH tunnel, or behind a reverse proxy, **not** a public unauthed service on plain HTTP. See [SECURITY.md](SECURITY.md).

## Develop

```bash
pip install -e ".[dev]"
make dev      # serve ./docs locally (theme gallery, live reload)
make test     # pytest
make lint     # ruff
```

`make help` lists every target. The full docs in [`docs/`](docs/) are themselves an oriel site.

---

> *An* oriel *is a bay window that projects out from a wall for a wider view — a window onto a folder.*

MIT — see [LICENSE](LICENSE).
