https://github.com/tropical-algae/markoun
A lightweight, self-hosted, and entirely file-based Markdown editor designed for users who prioritize privacy and simplicity.
https://github.com/tropical-algae/markoun
editor markdown markdown-editor markdown-language website
Last synced: about 1 month ago
JSON representation
A lightweight, self-hosted, and entirely file-based Markdown editor designed for users who prioritize privacy and simplicity.
- Host: GitHub
- URL: https://github.com/tropical-algae/markoun
- Owner: tropical-algae
- License: mit
- Created: 2026-01-20T10:53:06.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-05-03T14:50:28.000Z (about 2 months ago)
- Last Synced: 2026-05-03T16:30:25.855Z (about 2 months ago)
- Topics: editor, markdown, markdown-editor, markdown-language, website
- Language: Vue
- Homepage:
- Size: 8.4 MB
- Stars: 52
- Watchers: 1
- Forks: 6
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
A self-hosted, file-based Markdown editor
Markoun is a lightweight, self-hosted, and entirely file-based Markdown editor designed for users who prioritize privacy and simplicity.
> The UI layout of Markoun is inspired by [Haptic](https://github.com/chroxify/haptic) and [Obsidian](https://github.com/obsidianmd) — both excellent Markdown editing tools.
## Features
- **Clean UI**: Minimal interface with smooth animations and complete core editing features
- **File-Based Architecture**: Works directly on local files — no database, no indexing, fully portable
- **LaTeX support**: Live Markdown preview with built-in LaTeX support
- **Image Upload**: Supports file upload and `Ctrl + V ` clipboard image paste
- **Rich Configuration**: Flexible config.yaml options for logging, authentication, and file control
## Deployment
You can deploy Markoun using Docker:
```
export MARKOUN_PORT=10000
export MARKOUN_ROOT=./
touch ${MARKOUN_ROOT:-./}/config.yaml
docker run -itd --name markoun \
--restart unless-stopped \
-p ${MARKOUN_PORT:-10000}:80 \
-v ${MARKOUN_ROOT:-$(pwd)}/data:/app/data \
-v ${MARKOUN_ROOT:-$(pwd)}/config.yaml:/app/config.yaml \
tropicalalgae/markoun:latest
```
Then run `docker logs -f markoun` to check the logs for the default administrator password.
You can also create a new regular user from the homepage.
### Volume Explanation
| **Path** | **Description** |
| ------------------ | ------------------------------------------------- |
| `/app/data ` | Directory where Markdown files are stored. |
| `/app/config.yaml` | Main configuration file. |
| `/app/welcome.md` | Optional welcome note shown when no file is open. |
If you want to customize the default welcome page in Docker, mount your own Markdown file to `/app/welcome.md`, or point `WELCOME_NOTE_PATH` at a different mounted location.
## Configuration
Markoun is configured via a `config.yaml` file. Below are some important options:
| **Key** | **Description** | **Default** |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `DEBUG` | Enables/disable debug-level logging for the backend service. | false |
| `ACCESS_TOKEN_DEFAULT_EXPIRE_MINUTES` | **Standard Session Lifetime**: Duration (in minutes) a user remains logged in before the session expires. | 1440 |
| `ACCESS_TOKEN_EXTENDED_EXPIRE_MINUTES` | **Persistent Session Lifetime**: Duration (in minutes) for users who select "Remember Me" during login. | 43200 |
| `DISPLAYED_FILE_TYPES` | **File Filter**: A list of file extensions that the editor is permitted to display. | ["md", "png", "jpg", "jpeg", "bmp", "svg"] |
| `WELCOME_NOTE_PATH` | Path to the Markdown file used as the default welcome page when no document is open. | `./welcome.md` |
For more configurable options, see [config.py](src/markoun/common/config.py)
## Editor Details
**Relative Image Paths**:
When inserting images into a Markdown file, image paths are generated relative to the Markdown file’s location — not the project root. This ensures portability and correct rendering even if folders are moved.
**Rename by Long Press**:
Long-press on a file or folder name in the sidebar to rename it.
**Drag-and-Drop Upload**:
Drag a local file onto a folder in the sidebar to upload it directly into that folder.
**File Visibility Rules**:
By default, the sidebar displays only Markdown files and common image formats. To show additional file types, modify DISPLAYED_FILE_TYPES in config.yaml.
**System configuration**:
The administrator can enable or disable user registration in the settings section of the sidebar.
## Limitations & Roadmap
- [x] **Image security**: static image routes currently lack authentication checks
- [x] **File system architecture**: design can be further optimized
- [x] **UI polish**: incomplete animation feedback and styling inconsistencies
- [ ] **Settings expansion**: add more configurable options for personalization and workflow control
- [ ] **Quick actions & interaction enhancements**: support more intuitive and efficient operations
- [x] **Improved usability**: provide a smoother and more comfortable operation experience
- [x] **Enhanced previews**: support richer previews, including image preview and ~~Gantt chart rendering~~ in Markdown files
- [ ] **Frontend refactoring**: codebase requires further optimization
- [ ] **File synchronization**: support syncing files with a remote source
- [ ] **Version management**: introduce file versioning with history tracking and restore capability
## License
This project is licensed under the [MIT License](https://github.com/tropical-algae/markoun/blob/main/LICENSE).