207 lines
4.5 KiB
Markdown
207 lines
4.5 KiB
Markdown
# Markdown Editor
|
|
|
|
A full-featured markdown editor with live preview, built with modern web technologies.
|
|
|
|
## Features
|
|
|
|
- **Real-time Preview**: See your markdown rendered as you type
|
|
- **Syntax Highlighting**: Powered by CodeMirror with support for multiple languages
|
|
- **File Management**: Create, save, load, and delete markdown files
|
|
- **Mermaid Diagrams**: Render beautiful diagrams directly in your markdown
|
|
- **HTML Support**: Embed HTML snippets in your markdown
|
|
- **Synchronized Scrolling**: Editor and preview scroll together
|
|
- **Responsive Design**: Works on desktop and mobile devices
|
|
|
|
## Supported Languages
|
|
|
|
The editor provides syntax highlighting for:
|
|
|
|
- Markdown
|
|
- JavaScript
|
|
- Python
|
|
- HTML/CSS
|
|
- Go
|
|
- Rust
|
|
- JSON
|
|
- TOML
|
|
- YAML
|
|
- And more!
|
|
|
|
## Technology Stack
|
|
|
|
### Frontend
|
|
- **Bootstrap 5**: Modern, responsive UI framework
|
|
- **CodeMirror 5**: Powerful code editor component
|
|
- **Marked.js**: Fast markdown parser
|
|
- **Mermaid**: Diagram and flowchart rendering
|
|
- **Unpoly**: Progressive enhancement library
|
|
|
|
### Backend
|
|
- **FastAPI**: Modern Python web framework
|
|
- **Uvicorn**: ASGI server
|
|
- **uv (Astral)**: Fast Python package installer and environment manager
|
|
|
|
## Installation & Usage
|
|
|
|
### Quick Start
|
|
|
|
1. Navigate to the project directory:
|
|
```bash
|
|
cd markdown-editor
|
|
```
|
|
|
|
2. Run the startup script:
|
|
```bash
|
|
./start.sh
|
|
```
|
|
|
|
The script will:
|
|
- Install uv if not present
|
|
- Create a virtual environment
|
|
- Install all Python dependencies
|
|
- Create a sample markdown file
|
|
- Start the development server
|
|
|
|
3. Open your browser and navigate to:
|
|
```
|
|
http://localhost:8000
|
|
```
|
|
|
|
### Manual Installation
|
|
|
|
If you prefer to install manually:
|
|
|
|
```bash
|
|
# Install dependencies with uv
|
|
uv venv
|
|
uv pip install -e .
|
|
|
|
# Start the server
|
|
uv run uvicorn server:app --host 0.0.0.0 --port 8000 --reload
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
markdown-editor/
|
|
├── data/ # Markdown files storage
|
|
├── static/ # Static assets
|
|
│ ├── app.js # Main JavaScript application
|
|
│ └── style.css # Custom styles
|
|
├── templates/ # HTML templates
|
|
│ └── index.html # Main editor page
|
|
├── server.py # FastAPI backend server
|
|
├── pyproject.toml # Python project configuration
|
|
├── start.sh # Installation and startup script
|
|
└── README.md # This file
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
The backend provides the following REST API endpoints:
|
|
|
|
- `GET /` - Serve the main editor page
|
|
- `GET /api/files` - List all markdown files
|
|
- `GET /api/files/{filename}` - Get content of a specific file
|
|
- `POST /api/files` - Create or update a file
|
|
- `DELETE /api/files/{filename}` - Delete a file
|
|
|
|
## Usage Guide
|
|
|
|
### Creating a New File
|
|
|
|
1. Click the **New** button in the navbar
|
|
2. Enter a filename in the input field (e.g., `my-document.md`)
|
|
3. Start typing your markdown content
|
|
4. Click **Save** to save the file
|
|
|
|
### Loading an Existing File
|
|
|
|
- Click on any file in the sidebar to load it into the editor
|
|
|
|
### Saving Changes
|
|
|
|
- Click the **Save** button or press `Ctrl+S` (Windows/Linux) or `Cmd+S` (Mac)
|
|
|
|
### Deleting a File
|
|
|
|
1. Load the file you want to delete
|
|
2. Click the **Delete** button
|
|
3. Confirm the deletion
|
|
|
|
### Using Mermaid Diagrams
|
|
|
|
Create a code block with the `mermaid` language identifier:
|
|
|
|
````markdown
|
|
```mermaid
|
|
graph TD
|
|
A[Start] --> B[Process]
|
|
B --> C[End]
|
|
```
|
|
````
|
|
|
|
### Embedding HTML
|
|
|
|
You can embed HTML directly in your markdown:
|
|
|
|
```markdown
|
|
<div style="color: red;">
|
|
This is red text!
|
|
</div>
|
|
```
|
|
|
|
## Keyboard Shortcuts
|
|
|
|
- `Ctrl+S` / `Cmd+S` - Save current file
|
|
|
|
## Development
|
|
|
|
### Requirements
|
|
|
|
- Python 3.11+
|
|
- uv (Astral) - Will be installed automatically by start.sh
|
|
|
|
### Running in Development Mode
|
|
|
|
The server runs with auto-reload enabled by default, so any changes to the Python code will automatically restart the server.
|
|
|
|
### Adding New Features
|
|
|
|
- Frontend code: Edit `static/app.js` and `static/style.css`
|
|
- Backend API: Edit `server.py`
|
|
- UI layout: Edit `templates/index.html`
|
|
|
|
## Troubleshooting
|
|
|
|
### Port Already in Use
|
|
|
|
If port 8000 is already in use, you can change it in `start.sh` or run manually:
|
|
|
|
```bash
|
|
uv run uvicorn server:app --host 0.0.0.0 --port 8080 --reload
|
|
```
|
|
|
|
### Dependencies Not Installing
|
|
|
|
Make sure uv is properly installed:
|
|
|
|
```bash
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
```
|
|
|
|
Then try running `./start.sh` again.
|
|
|
|
## License
|
|
|
|
MIT License - Feel free to use this project for any purpose.
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Feel free to submit issues or pull requests.
|
|
|
|
---
|
|
|
|
**Happy writing!** 📝✨
|
|
|