From 2649cca69dbfb601491f17249ef8f05852212974 Mon Sep 17 00:00:00 2001 From: xiaomai Date: Sat, 1 Nov 2025 23:38:39 +0800 Subject: [PATCH] docs: add comprehensive project documentation and MIT license Replaces the generic Nuxt starter README with detailed documentation specific to the YPHS Alumni website project. The new README.md now includes: - Project overview, tech stack, and key features - Local development, build, and deployment instructions - Content authoring guide for news, events, and hall of fame - Project roadmap and contribution guidelines Additionally, this commit adds an MIT license file to formally establish the project's open-source status. --- LICENSE | 21 +++++ README.md | 264 ++++++++++++++++++++++++++++++++++++++++++------------ 2 files changed, 230 insertions(+), 55 deletions(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..3530b37 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 [Tootaio Studio] + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 25b5821..80810f5 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,229 @@ -# Nuxt Minimal Starter +# 永平中学校友会官网（YPHS Alumni） -Look at the [Nuxt documentation](https://nuxt.com/docs/getting-started/introduction) to learn more. +一个基于 Nuxt 4 与 Nuxt Content 打造的内容型网站，面向永平中学校友与社会公众，提供新闻公告、活动预告、名人堂与校友组织介绍等信息。项目内置基础的后台界面脚手架，支持后续扩展会员管理与内容发布流程。 -## Setup +![Nuxt](https://img.shields.io/badge/Nuxt-4-00DC82?logo=nuxt.js&logoColor=white) +![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white) +![TailwindCSS](https://img.shields.io/badge/TailwindCSS-4.x-06B6D4?logo=tailwindcss&logoColor=white) +![License](https://img.shields.io/badge/License-MIT-red) -Make sure to install dependencies: +- 线上地址：https://yphsalumni.org +- 技术栈：Nuxt 4（Vue 3 + Nitro）、TypeScript、Tailwind CSS 4、@nuxt/ui、@nuxt/content、@nuxt/image、SEO/Sitemap/Robots 模块 + +**项目亮点** +- 内容优先：使用 Markdown + 前置属性（Frontmatter）管理新闻、活动、名人堂。 +- 现代 UI：采用 @nuxt/ui + Tailwind CSS 4，内置响应式导航与主题样式。 +- SEO 友好：内置 @nuxtjs/seo、@nuxtjs/sitemap、@nuxtjs/robots 与合理的默认 `` 元信息。 +- 可扩展的后台：提供基础的「仪表盘 / 内容列表 / 模态编辑器」结构，便于后续对接真实后端。 +- 零后端即可上线：作为纯内容站点可静态导出部署，也可运行 SSR 部署。 + + +## 目录结构 + +关键目录说明： + +- `app/` + - `pages/` 路由页面（首页、新闻、活动、名人堂、关于、入会申请、后台等） + - `layouts/` 页面布局（`default`、`admin-dashboard`） + - `components/` 组件（首页模块、后台弹窗、输入组件等） + - `assets/css/` 样式（Tailwind 入口与 Markdown 样式） + - `composables/` 可复用逻辑（日期格式化、国家数据等） + - `data/` 静态数据（如国家拨号表） +- `content/` Markdown 内容（`news/`、`events/`、`hall-of-fames/`） +- `content.config.ts` 内容集合与字段 Schema 定义 +- `public/` 公开静态资源（Logo、封面图、音频、图片等） +- `nuxt.config.ts` Nuxt 主配置（模块、SEO、站点信息等） +- `docs/` 产品与信息架构文档 + + +## 功能概览 + +- 首页：英雄区 + 最新新闻 + 活动卡片 + 名人堂预览 + 捐赠占位模块 +- 新闻：列表与详情（Markdown 渲染，支持封面、标签、SEO 字段） +- 活动：列表与详情（日期/地点/封面，支持嵌入媒体） +- 名人堂：人物详情 + 图集 + 外链视频/媒体嵌入 +- 关于页面：会徽含义、校歌音频等 +- 入会申请：UI 表单（当前为占位，未连通后端） +- 后台（占位）：仪表盘、会员籍管理（示例数据）、新闻/活动/名人堂入口与新建弹窗（`md-editor-v3`） + + +## 环境要求 + +- Node.js ≥ 18.20 或 20.x（推荐 20 LTS） +- 包管理器：pnpm（推荐）/ npm / yarn / bun + +启用 pnpm（建议）： ```bash -# npm -npm install +corepack enable +corepack prepare pnpm@latest --activate +``` -# pnpm + +## 本地开发 + +安装依赖： +```bash pnpm install - -# yarn -yarn install - -# bun -bun install ``` -## Development Server - -Start the development server on `http://localhost:3000`: - +启动开发服务器（默认 http://localhost:3000）： ```bash -# npm -npm run dev - -# pnpm pnpm dev - -# yarn -yarn dev - -# bun -bun run dev ``` -## Production -Build the application for production: +## 构建与预览 +SSR 构建与本地预览： ```bash -# npm -npm run build - -# pnpm pnpm build - -# yarn -yarn build - -# bun -bun run build -``` - -Locally preview production build: - -```bash -# npm -npm run preview - -# pnpm pnpm preview - -# yarn -yarn preview - -# bun -bun run preview ``` -Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information. +静态导出（适合静态站部署，如 Netlify/Cloudflare Pages/Nginx 静态目录）： +```bash +pnpm generate +# 产物在 .output/public （仓库中有 dist -> .output/public 的软链） +``` + + +## 部署指引 + +- 静态托管：执行 `pnpm generate` 后，将 `.output/public`（或 `dist` 软链）上传到任意静态空间（如 Cloudflare Pages、Netlify、GitHub Pages、Nginx 静态目录）。 +- Node SSR：执行 `pnpm build` 后，以 Node 方式运行 `.output/server/index.mjs`，或使用平台的 Nuxt 运行时适配（Vercel/Netlify Functions/自托管 Node）。 +- SEO：请在 `nuxt.config.ts` 的 `site.url` 与 `app.head` 中更新为你自己的域名与元信息。 + + +## 内容写作与数据结构 + +项目使用 `@nuxt/content` 管理内容，字段规则见 `content.config.ts`。在对应目录新增 Markdown 文件即可出现在站点中。 + +示例：新闻（`content/news/20251001-official-web-launch.md`） +```md +--- +title: "永中校友会官网正式上线" +date: "2025-10-01" +updated: "2025-10-01" +author: "作者名" +description: "用于列表摘要与 SEO 的简短说明" +cover: "/news/20251001-official-web-launch/Screenshot.png" +tags: ["活动", "公告"] +category: "通知" +highlight: true +seoTitle: "SEO 标题" +seoDescription: "SEO 描述" +ogImage: "/images/og/news-launch.jpg" +--- + +正文使用 Markdown 书写，支持图片、表格、引用与 HTML 块。 +``` + +示例：活动（`content/events/20250927-return-to-school.md`） +```md +--- +title: "活动标题" +subtitle: "活动副标题" +date: "2025-09-27" +location: "地点名称" +cover: "/events/20250927-return-to-school/event-photo-1.jpg" +--- + +活动详情正文... +``` + +示例：名人堂（`content/hall-of-fames/he-si-rong.md`） +```md +--- +name: "人物姓名" +photo: "/hall-of-fame/he-si-rong/人物头像.png" +title: "人物头衔" +description: "简短介绍" +gallery: + [ + "/hall-of-fame/he-si-rong/图1.webp", + "/hall-of-fame/he-si-rong/图2.webp" + ] +--- + +正文可包含媒体嵌入。 +``` + + +## 定制与配置 + +- 站点信息与 SEO：`nuxt.config.ts` + - `app.head.titleTemplate` 与默认 `title` + - Meta、OG、Twitter 卡片默认值 + - `site.url`（用于站点地图与 SEO） +- 导航与页脚：`app/layouts/default.vue` +- 样式与主题色：`app/assets/css/main.css`（Tailwind v4 与自定义 CSS 变量） +- Markdown 渲染样式：`app/assets/css/markdown.css` +- 首页区块：`app/components/index/*.vue` +- TikTok 嵌入组件：`app/components/TikTokEmbed.vue` +- 后台布局与侧边导航：`app/layouts/admin-dashboard.vue`、`app/composables/useDashboardSidebarLinks.ts` +- 分析脚本：`public/analytics.js`（默认使用 Umami，若不需要可在 `nuxt.config.ts` 中移除 `