Metadata-Version: 2.4
Name: md-studio
Version: 1.0.3
Summary: Markdown CMS as a Python package - embed in FastAPI/Starlette applications
Author: Anik Datta
License: MIT
Project-URL: Homepage, https://github.com/Auniik/md-studio
Project-URL: Documentation, https://github.com/Auniik/md-studio#readme
Project-URL: Repository, https://github.com/Auniik/md-studio
Project-URL: Issues, https://github.com/Auniik/md-studio/issues
Keywords: markdown,cms,fastapi,starlette,documentation,md
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: FastAPI
Classifier: Framework :: AsyncIO
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: starlette>=0.27.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-frontmatter>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: httpx>=0.24.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.0.280; extra == "dev"

# MD Studio

A standalone Python package that provides a modern Markdown CMS for FastAPI and Starlette applications. 

## Features

- 📝 **Markdown-first**: Write content in Markdown with frontmatter support
- 🎨 **Modern UI**: React-based interface with dark mode
- 🚀 **Easy Integration**: Mount as an ASGI app in any FastAPI/Starlette app
- 📁 **Flexible Storage**: Filesystem storage for content and uploads
- 🔒 **Public Sharing**: Share documents publicly with unique URLs
- 📤 **Import/Export**: Bulk operations with ZIP archives
- 🖼️ **File Uploads**: Built-in file upload and attachment handling
- 🔍 **Search & Filter**: Full-text search with sorting and filtering

## Installation

```bash
pip install md-studio
```

## Quick Start

### FastAPI

```python
from fastapi import FastAPI
from md_studio import MDStudio

app = FastAPI()

app.mount(
    "/md-studio",
    MDStudio(
        title="My Documentation",
        scan_dirs=["./docs", "./markdowns", "./"],
        write_dir="./docs",
    )
)
```

Provide at least one of `scan_dirs` or `write_dir` (or set `MD_STUDIO_SCAN_DIRS`/`MD_STUDIO_WRITE_DIR`) so the content store can be located.
`scan_dirs` controls where existing content is scanned (list or comma-separated string).
`write_dir` selects where new/imported documents are saved.
`uploads_path` defaults to `<write_dir>/uploads` (or `<scan_dirs[0]>/uploads` if `write_dir` is unset).
`metadata_path` controls where the index metadata is stored (default: `<uploads_path>/.md-studio-metadata.json`).

### Starlette

```python
from starlette.applications import Starlette
from starlette.routing import Mount
from md_studio import MDStudio

app = Starlette(
    routes=[
        Mount(
            "/md-studio",
            MDStudio(
                title="My Markdown Docs",
                scan_dirs=["./docs", "./markdowns", "./"],
                write_dir="./docs",
            )
        )
    ]
)
```

### Run the server

```bash
uvicorn main:app --reload
```

Then visit `http://localhost:8000/md-studio`

## Frontend build (SPA)

The UI is a Remix SPA that is built with Node.js and then served by the Python package.
No Node runtime is needed in production, but Node is required to build the static assets.

```bash
cd ui
npm install
npm run build
```

The build output in `ui/build/client` should be copied to `md_studio/static`.
You can use the helper script:

```bash
bash ./build_and_run.sh
```

Note: Some dependencies require Node 20.19+, 22.12+, or 24+ to avoid EBADENGINE warnings.

## Configuration

```python
MDStudio(
    scan_dirs=["./docs", "./markdowns", "./"],            # Where existing markdown files are scanned
    write_dir="./docs",              # Where new/imported markdown files are written
    uploads_path="./docs/uploads",   # Optional override (defaults to write_dir/uploads)
    metadata_path="./docs/uploads/.md-studio-metadata.json",  # Optional override
    title="MD Studio",
)
```

### Environment Variables

- `MD_STUDIO_SCAN_DIRS`: Comma-separated scan roots (alternative to `scan_dirs`)
- `MD_STUDIO_CONTENT_DIRS`: Legacy alias for `MD_STUDIO_SCAN_DIRS`
- `MD_STUDIO_WRITE_DIR`: Write root for new/imported documents
- `MD_STUDIO_API_PATH`: API prefix injected into the frontend (default: `/md/api`)

For deployment to production environments, see [DEPLOYMENT.md](DEPLOYMENT.md).

## License

MIT License - see LICENSE file for details

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
