Aran Roig
5feeeabbf7
All checks were successful
Build and Deploy Nuxt / build (push) Successful in 23s
76 lines
3.1 KiB
Markdown
76 lines
3.1 KiB
Markdown
# Mathew — a wiki for mathematics
|
|
|
|
A modern math-concept wiki. Articles are written in **Markdown** (with **LaTeX** via KaTeX)
|
|
and stored in MongoDB through an Express API.
|
|
|
|
```
|
|
mathew/
|
|
├── backend/ Express 5 + Mongoose API (port 5000)
|
|
└── frontend/ Nuxt 4 wiki UI (port 3000/3001)
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
# 1. API (requires MongoDB on localhost:27017)
|
|
cd backend
|
|
npm install
|
|
npm run seed # optional: 6 sample articles (LaTeX included)
|
|
npm run dev # → http://localhost:5000
|
|
|
|
# 2. UI
|
|
cd ../frontend
|
|
npm install
|
|
npm run dev # → http://localhost:3000
|
|
```
|
|
|
|
## Pages
|
|
|
|
| Route | What it does |
|
|
| --- | --- |
|
|
| `/` | Search + recently updated articles |
|
|
| `/wiki/<lang>/<slug>` | One language version of an article, with its table of contents — every version has an address of its own, English included (`/wiki/en/…`) |
|
|
| `/wiki/<slug>` | The short form, naming no language: it is turned onto the address of the version the slug speaks |
|
|
| `/wiki/<lang>/<slug>/edit` — `/wiki/<slug>/edit` | Markdown editor with live preview |
|
|
| `/new` | Create a new article |
|
|
|
|
## Markdown + LaTeX
|
|
|
|
Articles support GitHub-ish Markdown (headings, tables, lists, blockquotes, fenced
|
|
code with highlighting) plus LaTeX: `$E = mc^2$` inline and `$$ ... $$` in display
|
|
mode. Rendered server-side with `markdown-it` + `markdown-it-texmath` + KaTeX and
|
|
sanitized with DOMPurify (raw HTML in articles is escaped).
|
|
|
|
Handy macros: `\R`, `\N`, `\Z`, `\Q`, `\C` for the number sets.
|
|
|
|
## API
|
|
|
|
| Method | Endpoint |
|
|
| --- | --- |
|
|
| GET | `/api/articles?q=&tag=&lang=&limit=&offset=` — search / filter, paged **by article** (`{ articles, total, hasMore }`; no `limit` means the whole shelf, and `?lang=` answers each article as the version written in it) |
|
|
| GET | `/api/articles/facets` — `{ total, topics, languages }` counted over the whole shelf |
|
|
| GET | `/api/articles/slug/:slug` — one article |
|
|
| POST | `/api/articles` — create (`title` required; slug auto-generated & uniquified) |
|
|
| PUT | `/api/articles/slug/:slug` — update |
|
|
| DELETE | `/api/articles/slug/:slug` — delete |
|
|
|
|
## Configuration
|
|
|
|
| Where | Variable | Default | Meaning |
|
|
| --- | --- | --- | --- |
|
|
| `backend/.env` | `PORT` | `5000` | API port |
|
|
| `backend/.env` | `MONGO_URI` | `mongodb://127.0.0.1:27017/mathew` | Mongo connection |
|
|
| `frontend` env | `NUXT_PUBLIC_API_BASE` | `http://localhost:5000` | Where the UI calls the API |
|
|
| `frontend` build | `NUXT_API_PROXY_TARGET` | `http://localhost:5000` | Where the Nuxt server's own (SSR) `/api` calls are forwarded |
|
|
|
|
In Docker the frontend image builds with `NUXT_PUBLIC_API_BASE=` (empty): the browser calls
|
|
`/api` on its own origin and nginx routes it to `http://backend:5000` — the same hop answers
|
|
the Nuxt server's SSR calls, which the image points at the backend container via
|
|
`NUXT_API_PROXY_TARGET`.
|
|
|
|
## Editing tips
|
|
|
|
- `/` focuses the search box on the home page; `Ctrl/Cmd+S` saves in the editor.
|
|
- The editor has Write / Split / Preview modes; LaTeX and code highlight update live.
|
|
- Changing an article's title may change its slug (old links 404 — redirect not implemented).
|