# markdown-notes

**Repository Path**: cutecuteyu/markdown-notes

## Basic Information

- **Project Name**: markdown-notes
- **Description**: markdown笔记软件
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-29
- **Last Updated**: 2026-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Markdown Notes Application

A fully-featured Markdown notes application with a **Vue 3 + Vite** frontend and **Go + Gin** backend, using JSON file persistence.

---

## Table of Contents

- [Features](#features)
- [Tech Stack](#tech-stack)
- [Project Structure](#project-structure)
- [Quick Start](#quick-start)
  - [Prerequisites](#prerequisites)
  - [Installation](#installation)
  - [Running the Application](#running-the-application)
- [API Documentation](#api-documentation)
- [Deployment](#deployment)
- [Architecture](#architecture)
  - [Backend Architecture](#backend-architecture)
  - [Frontend Architecture](#frontend-architecture)
  - [Data Flow](#data-flow)

---

## Features

- **Markdown Editing & Live Preview** — Support for headings, bold, italic, code blocks, links, lists, quotes, and more
- **Toolbar Quick Insert** — One-click insertion of Markdown syntax, no need to memorize syntax
- **Auto-Save** — Automatically saves 2 seconds after you stop typing, with "Saving... / Saved" status feedback
- **Note Search** — Search by title and content simultaneously with real-time filtering
- **Full Chinese Interface** — All UI text, prompts, and error messages are in Chinese
- **RESTful API** — Complete CRUD endpoints with standard JSON responses
- **Dual-Mode Deployment** — Development mode supports frontend/backend separation with hot reload, production mode supports single-port deployment

---

## Tech Stack

| Layer | Technology | Description |
|-------|------------|-------------|
| Frontend Framework | Vue 3 (Composition API) | Using `<script setup>` + composables |
| Build Tool | Vite 5 | Dev server with HMR support |
| Markdown Rendering | marked | Renders Markdown text to HTML |
| Backend Framework | Go + Gin | High-performance HTTP framework |
| Data Storage | JSON Files | Local file system persistence, no database required |
| Data Model | UUID v4 | Using google/uuid for unique identifiers |

---

## Project Structure

```
markdown-notes/
├── backend/                          # Go backend service
│   ├── main.go                       # Entry file (routing, server startup)
│   ├── go.mod                        # Go module definition
│   ├── go.sum                        # Dependency checksums
│   ├── handlers/
│   │   └── notes.go                  # HTTP request handlers
│   ├── middleware/
│   │   └── cors.go                   # CORS middleware
│   ├── models/
│   │   └── note.go                   # Data model definitions
│   └── storage/
│       ├── store.go                  # Storage interface (abstraction layer)
│       └── json_store.go             # JSON file storage implementation
│
├── frontend/                         # Vue 3 frontend application
│   ├── index.html                    # HTML entry point
│   ├── package.json                  # Dependencies declaration
│   ├── vite.config.js                # Vite configuration (with API proxy)
│   └── src/
│       ├── main.js                   # Vue app entry
│       ├── style.css                 # Global styles
│       ├── config.js                 # App configuration (API URL, etc.)
│       ├── api/
│       │   └── index.js              # API client (wrapped fetch)
│       ├── composables/
│       │   └── useNotes.js           # Notes business logic composable
│       ├── components/
│       │   ├── NoteList.vue          # Sidebar note list component
│       │   └── NoteEditor.vue        # Note editor component
│       └── App.vue                   # Root component (layout)
│
└── README.md                         # This file
```

---

## Quick Start

### Prerequisites

- **Go** 1.21 or higher ([download](https://go.dev/dl/))
- **Node.js** 18 or higher ([download](https://nodejs.org/))
- **npm** 9 or higher (installed with Node.js)

### Installation

1. Navigate to the project directory:

   ```bash
   cd markdown-notes
   ```

2. Install backend dependencies:

   ```bash
   cd backend
   go mod download
   cd ..
   ```

3. Install frontend dependencies:

   ```bash
   cd frontend
   npm install
   cd ..
   ```

### Running the Application

**Development Mode** (recommended, with hot reload):

Open two terminal windows to run backend and frontend separately.

Terminal 1 — Start backend service (port 8080):

```bash
cd backend
go run .
```

Terminal 2 — Start frontend dev server (port 5173):

```bash
cd frontend
npm run dev
```

Then open **http://localhost:5173** in your browser.

> The Vite dev server is configured with a proxy, so `/api/*` requests are automatically forwarded to the backend at `http://localhost:8080`, no additional configuration needed.

**Production Mode** (single-port deployment):

```bash
cd frontend
npm run build          # Build frontend to dist/
cd ../backend
go run .               # Backend serves static files
```

Open **http://localhost:8080** in your browser, no need to start the frontend dev server.

---

## API Documentation

All API endpoints are prefixed with `/api`, with JSON request/response format.

### Note Model

```json
{
  "id": "uuid-string",
  "title": "Note title",
  "content": "Markdown formatted content",
  "created_at": "2026-04-29T00:00:00+08:00",
  "updated_at": "2026-04-29T00:00:00+08:00"
}
```

### Endpoints

| Method | Path | Description | Request Body | Response |
|--------|------|-------------|--------------|----------|
| GET | `/api/notes` | Get all notes | — | `{"notes": [...]}` |
| GET | `/api/notes/:id` | Get a single note | — | Note object |
| POST | `/api/notes` | Create a note | `{"title": "required", "content": "optional"}` | New note object |
| PUT | `/api/notes/:id` | Update a note | `{"title": "optional", "content": "optional"}` | Updated note object |
| DELETE | `/api/notes/:id` | Delete a note | — | `{"message": "Note deleted"}` |

### Status Codes

- **200** — Success
- **201** — Created
- **400** — Bad request (e.g., empty title, invalid JSON)
- **404** — Note not found
- **500** — Internal server error

---

## Deployment

### Building for Production

```bash
# Build frontend
cd frontend
npm run build

# Build backend executable
cd ../backend
go build -o notes-app .

# Run (Windows)
notes-app.exe

# Run (Linux/macOS)
./notes-app
```

After building, the backend binary automatically serves frontend static files from `../frontend/dist/`, enabling single-port deployment.

### Custom Port

Modify the port number in `backend/main.go`:

```go
r.Run(":8080")  // Change 8080 to your desired port
```

---

## Architecture

### Backend Architecture

The backend uses a layered architecture with clear responsibilities and unidirectional dependencies:

```
main.go (routing / startup)
  │
  ├──→ middleware/cors.go (CORS middleware)
  │
  └──→ handlers/notes.go (HTTP request handlers)
         │                   Depends on Store interface, not concrete implementation
         ↓
       storage/store.go (Store interface)
         ↑                   
       storage/json_store.go (JSON file implementation)
         │
         └──→ models/note.go (Data model)
```

**Key Design:** The handlers layer accesses data through the `storage.Store` **interface** (not concrete types), making the storage backend replaceable without affecting business logic. For example, switching to MySQL only requires creating a new `MySQLStore` that implements the `Store` interface.

### Frontend Architecture

The frontend uses Vue 3 Composition API with layered design:

```
App.vue (Layout layer: component composition)
  │
  ├──→ composables/useNotes.js (Business logic: state management + CRUD)
  │       │
  │       └──→ api/index.js (Network layer: HTTP wrapper)
  │               │
  │               └──→ config.js (Config: API URL, constants)
  │
  ├──→ components/NoteList.vue (UI: sidebar list)
  │
  └──→ components/NoteEditor.vue (UI: editor)
```

**Key Design:** All business logic is extracted into the `useNotes` composable, App.vue only handles component composition. UI components receive data via props and emit events, never modifying data directly.

### Data Flow

```
User Action → Vue Component (emit event) → useNotes (business logic)
                                          ↓
                                    noteApi (HTTP request)
                                          ↓
                               Go Backend Gin API (handlers)
                                          ↓
                                    JSONStore (read/write files)
                                          ↓
                                    data/notes.json
```

Auto-save flow:

1. User types in editor
2. Wait 2 seconds with no new input, trigger auto-save
3. NoteEditor emits `save` event to parent
4. App.vue calls `useNotes().saveNote()`
5. `saving` set to `true`, display "Saving..."
6. Call `noteApi.update()` to send PUT request
7. Backend updates JSON file and returns new data
8. `saving` set to `false`, display "Saved"

---

## License

MIT