Skip to content

Commit 4d31417

Browse files
PttCodingManPttCodingMan
committed
docs: update README.
1 parent 667c59c commit 4d31417

3 files changed

Lines changed: 291 additions & 241 deletions

File tree

‎README.en.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
<p align="center">
2+
<img src="docs/images/logo.png" alt="JustWiki Logo" width="480">
3+
</p>
4+
5+
<p align="center">
6+
<strong>English</strong> · <a href="README.md">中文</a>
7+
</p>
8+
9+
# JustWiki
10+
11+
A lightweight, self-hosted wiki for small teams. Just clone, run, and write.
12+
13+
## Why JustWiki
14+
15+
Built for "small team, no ops headaches":
16+
17+
- **vs Outline** — no PostgreSQL / Redis / MinIO, no 4 CPU / 8 GB box; a 1 vCPU / 512 MB VM — or even a Raspberry Pi — runs it fine
18+
- **vs Wiki.js** — v3 has been "coming soon" since 2021 with no beta; v2 is in maintenance. JustWiki is actively developed
19+
- **vs BookStack** — unlimited page nesting, not capped at Book → Chapter → Page
20+
- **vs Notion / Obsidian** — self-hosted, your data on your own machine, with full multi-user collaboration (ACL, comments, page subscriptions) — not cloud lock-in or a single-user notebook
21+
22+
All your data = one `data/just-wiki.db` SQLite file + the `media/` folder. Backup, migration, and export are just copying files.
23+
24+
## Features
25+
26+
**Editing & content**
27+
- **Markdown first** — Milkdown WYSIWYG editor with slash commands, Mermaid diagrams, KaTeX math, callout blocks
28+
- **Wikilinks** — `[[page]]` syntax with automatic backlink tracking
29+
- **Page hierarchy & templates** — nested page trees, one-click reusable templates
30+
- **Draw.io integration** — embedded diagram editor
31+
32+
**Views & search**
33+
- **Multiple views** — tree and graph (with 3D / 2D-plane toggle)
34+
- **Full-text search** — FTS5 powered, with optional Gemini AI Q&A
35+
- **Readable CJK URLs** — page URLs keep the original Chinese/Japanese/Korean title instead of mangling it into `%E4%B8...` escapes
36+
37+
**Collaboration & permissions**
38+
- **Multi-user + group ACL** — per-page permission control
39+
- **Version history** — page revisions with diff view
40+
- **Comments, bookmarks, tags, page subscriptions** — everything a small team needs
41+
- **Activity log & trash** — see recent changes, recover deleted pages
42+
43+
**Export & deployment**
44+
- **Flexible export** — per-page Markdown / HTML / PDF (browser print), full-site static zip
45+
- **One SQLite file** — no external database needed. Backup = copy one file
46+
- **Themes** — 9 built-in color palettes ([preview](#themes))
47+
- **Docker support** — `docker-compose up` and done
48+
49+
## Themes
50+
51+
<p align="center">
52+
<img src="docs/images/themes.png" alt="9 built-in themes: Light, Dark, Lavender, Forest, Rose, Ocean, Sand, Sunset, Nord" width="100%">
53+
</p>
54+
55+
Nine curated palettes ship out of the box — **Light, Dark, Lavender, Forest, Rose, Ocean, Sand, Sunset, Nord**. Switch any time from the top-right theme picker; your choice is remembered per browser.
56+
57+
## Deployment
58+
59+
### Docker (Recommended)
60+
61+
The fastest way to get JustWiki running is with Docker Compose.
62+
63+
```bash
64+
cp .env.example .env
65+
# edit .env — at minimum change SECRET_KEY and ADMIN_PASS
66+
docker-compose up -d
67+
```
68+
69+
Open http://localhost:3000 to start writing.
70+
71+
### Configuration
72+
73+
All settings live in a single `.env` file. See [.env.example](.env.example) for available options.
74+
75+
Key variables:
76+
77+
| Variable | Description | Default |
78+
| --------------- | ---------------------------------- | -------------------- |
79+
| `SECRET_KEY` | Session signing key | `change-me-...` |
80+
| `ADMIN_USER` | Admin username | `admin` |
81+
| `ADMIN_PASS` | Admin password | `admin` |
82+
| `DB_PATH` | SQLite database path | `./data/just-wiki.db`|
83+
| `AI_ENABLED` | Enable Gemini AI Q&A | `false` |
84+
| `GEMINI_API_KEY`| Gemini API key (when AI enabled) | |
85+
86+
## Usage
87+
88+
### Slash Commands
89+
90+
<p align="center">
91+
<img src="docs/images/slash-commands.png" alt="Type / in the editor to open the slash command menu" width="80%">
92+
</p>
93+
94+
In the editor, type `/` to open the slash menu. You can filter by typing after the slash.
95+
96+
| Command | Description |
97+
| ------- | ----------- |
98+
| `/h1` | Heading 1 — big section heading |
99+
| `/h2` | Heading 2 — medium section heading |
100+
| `/h3` | Heading 3 — small section heading |
101+
| `/bullet` | Bullet List — unordered list |
102+
| `/ordered` | Ordered List — numbered list |
103+
| `/quote` | Blockquote — quote block |
104+
| `/code` | Code Block — code snippet |
105+
| `/hr` | Divider — horizontal rule |
106+
| `/callout-info` | Info Callout — `:::info` block |
107+
| `/callout-warning` | Warning Callout — `:::warning` block |
108+
| `/callout-tip` | Tip Callout — `:::tip` block |
109+
| `/callout-danger` | Danger Callout — `:::danger` block |
110+
| `/mermaid` | Mermaid Diagram — insert mermaid chart |
111+
| `/math` | Math Formula — KaTeX math block |
112+
| `/drawio` | Draw.io Diagram — insert Draw.io embed |
113+
114+
---
115+
116+
## Development Guide
117+
118+
### Tech Stack
119+
120+
| Layer | Stack |
121+
| -------- | ---------------------------------------------- |
122+
| Backend | Python, FastAPI, aiosqlite, Pydantic |
123+
| Frontend | React 19, Vite, Tailwind CSS 4, Zustand |
124+
| Editor | Milkdown (ProseMirror) |
125+
| Database | SQLite (single file) |
126+
| Deploy | Docker Compose |
127+
128+
### Local Development
129+
130+
1. **Setup**: Install backend & frontend dependencies and create `.env`
131+
```bash
132+
make setup
133+
```
134+
*Requires: Python 3.11+, Node.js 20+, [uv](https://docs.astral.sh/uv/)*
135+
136+
2. **Run**: Start backend (port 8000) and frontend (port 3000)
137+
```bash
138+
make dev
139+
```
140+
141+
### Makefile Commands
142+
143+
| Command | Description |
144+
| ------- | ----------- |
145+
| `make dev` | Start backend + frontend in dev mode |
146+
| `make dev-backend` | Start backend only |
147+
| `make dev-frontend` | Start frontend only |
148+
| `make build` | Build frontend for production |
149+
| `make backup` | Backup SQLite database with timestamp |
150+
| `make clean` | Remove database, media, and frontend dist |
151+
| `make docker-up` | `docker-compose up -d` |
152+
| `make docker-down` | `docker-compose down` |
153+
| `make setup` | First-time setup (install deps, create .env) |
154+
155+
### Project Structure
156+
157+
```
158+
justwiki/
159+
├── backend/ # FastAPI REST API
160+
│ └── app/
161+
│ ├── main.py
162+
│ ├── routers/ # pages, search, media, tags, versions, ...
163+
│ └── services/ # markdown, search, AI, webhook, export
164+
├── frontend/ # React SPA (Vite)
165+
│ └── src/
166+
│ ├── components/
167+
│ │ ├── Editor/ # Milkdown editor
168+
│ │ ├── Viewer/ # Markdown renderer
169+
│ │ ├── Search/ # Search + AI Q&A
170+
│ │ └── Layout/ # Sidebar, Navbar
171+
│ ├── pages/
172+
│ ├── hooks/
173+
│ └── store/ # Zustand
174+
├── data/ # Runtime data (SQLite, media)
175+
├── docker-compose.yml
176+
├── Makefile
177+
└── .env.example
178+
```
179+
180+
## License
181+
182+
This project is licensed under the [MIT License](LICENSE).

0 commit comments

Comments
 (0)