{"id":48792693,"url":"https://github.com/pplmx/x-blog","last_synced_at":"2026-04-13T21:06:49.209Z","repository":{"id":350628816,"uuid":"1207653175","full_name":"pplmx/x-blog","owner":"pplmx","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-11T09:54:35.000Z","size":272,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-11T10:08:17.922Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pplmx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-11T08:03:36.000Z","updated_at":"2026-04-11T09:54:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pplmx/x-blog","commit_stats":null,"previous_names":["pplmx/x-blog"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pplmx/x-blog","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pplmx%2Fx-blog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pplmx%2Fx-blog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pplmx%2Fx-blog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pplmx%2Fx-blog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pplmx","download_url":"https://codeload.github.com/pplmx/x-blog/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pplmx%2Fx-blog/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31770826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T20:17:16.280Z","status":"ssl_error","status_checked_at":"2026-04-13T20:17:08.216Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-13T21:06:48.516Z","updated_at":"2026-04-13T21:06:49.202Z","avatar_url":"https://github.com/pplmx.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# X-Blog\n\n\u003cdiv align=\"center\"\u003e\n\n![Next.js](https://img.shields.io/badge/Next.js-16-black?style=for-the-badge\u0026logo=next.js)\n![FastAPI](https://img.shields.io/badge/FastAPI-0.135-009989?style=for-the-badge\u0026logo=fastapi)\n![TypeScript](https://img.shields.io/badge/TypeScript-6-3178C6?style=for-the-badge\u0026logo=typescript)\n![Python](https://img.shields.io/badge/Python-3.14-3776AB?style=for-the-badge\u0026logo=python)\n\nA modern full-stack blog application built with FastAPI + Next.js\n\n[English](./README.md) · [中文](./README.zh-CN.md)\n\n\u003c/div\u003e\n\n## ✨ Features\n\n- 🚀 **Modern Tech Stack** - Next.js 16, FastAPI, TypeScript 6, Python 3.14\n- 📝 **Markdown Support** - Write posts with Mermaid diagrams, KaTeX math, code highlighting\n- 🎨 **Beautiful UI** - Clean design with Tailwind CSS v4 + shadcn/ui\n- 📱 **Responsive** - Mobile-friendly responsive layout\n- 🔒 **Admin Panel** - Built-in admin dashboard for content management\n- 🧪 **Well Tested** - 154 tests (68 backend + 86 frontend)\n- ✅ **Type Safe** - Full TypeScript support + Pydantic validation\n- 🔍 **Full-text Search** - Post search functionality\n- 🌙 **Dark Mode** - System preference aware dark mode\n- 📊 **Reading Analytics** - View counts, like counts, reading progress\n- 💬 **Comments** - Nested comment support with replies\n- 🏷️ **Tags \u0026 Categories** - Organize posts with tags and categories\n- 📱 **PWA Support** - Installable as a web app\n- 🎯 **SEO Optimized** - Open Graph, JSON-LD structured data\n- ⬆️ **Pinned Posts** - Pin important posts to top\n- 📤 **Data Export** - Export posts/comments as CSV\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n| Tool    | Version | Install                               |\n| ------- | ------- | ------------------------------------- |\n| Python  | 3.14+   | [uv](https://github.com/astral-sh/uv) |\n| Node.js | 24+     | [Node.js](https://nodejs.org/)        |\n| pnpm    | 10+     | `npm install -g pnpm`                 |\n| just    | 1.0+    | [just](https://github.com/casey/just) |\n\n```bash\n# Install uv (Python package manager)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n### Installation\n\n```bash\n# Install all dependencies\njust install\n\n# Or manually:\ncd backend \u0026\u0026 uv sync\ncd frontend \u0026\u0026 pnpm install\n```\n\n### Development\n\n```bash\n# Run both backend and frontend\njust dev\n\n# Or run separately:\njust backend  # http://localhost:8000\njust frontend # http://localhost:3000\n```\n\n### 🐳 Docker Deployment\n\n```bash\n# Clone and start\ngit clone https://github.com/your-username/x-blog.git\ncd x-blog\n\n# Configure environment\ncp backend/.env.example backend/.env\n\n# Start with Docker Compose\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f\n```\n\nSee [docs/deployment.md](./docs/deployment.md) for detailed deployment guide.\n\n## 🛠️ Commands\n\n| Command              | Description                              |\n| -------------------- | ---------------------------------------- |\n| `just install`       | Install all dependencies                 |\n| `just dev`           | Run dev servers (backend + frontend)     |\n| `just backend`       | Run FastAPI server                       |\n| `just frontend`      | Run Next.js dev server                   |\n| `just lint`          | Lint code (ruff + biome)                 |\n| `just format`        | Format code                              |\n| `just test`          | Run all tests (68 backend + 86 frontend) |\n| `just test-backend`  | Run backend tests (parallel)             |\n| `just test-frontend` | Run frontend tests                       |\n| `just fix`           | Auto-fix lint issues                     |\n| `just ci`            | Run lint + format + test                 |\n| `just clean`         | Clean generated files                    |\n\n## 📡 API Endpoints\n\n### Posts\n\n| Method | Endpoint                  | Description            |\n| ------ | ------------------------- | ---------------------- |\n| GET    | `/api/posts`              | List posts (paginated) |\n| GET    | `/api/posts/{slug}`       | Get post by slug       |\n| GET    | `/api/posts/{id}/related` | Get related posts      |\n| POST   | `/api/posts`              | Create post            |\n| PUT    | `/api/posts/{id}`         | Update post            |\n| DELETE | `/api/posts/{id}`         | Delete post            |\n| POST   | `/api/posts/{id}/like`    | Like a post            |\n| POST   | `/api/posts/{id}/view`    | Increment view count   |\n\n### Categories \u0026 Tags\n\n| Method | Endpoint                   | Description           |\n| ------ | -------------------------- | --------------------- |\n| GET    | `/api/categories`          | List categories       |\n| GET    | `/api/tags`                | List tags             |\n| GET    | `/api/posts?tag_id=X`      | Get posts by tag      |\n| GET    | `/api/posts?category_id=X` | Get posts by category |\n\n### Comments\n\n| Method | Endpoint                  | Description           |\n| ------ | ------------------------- | --------------------- |\n| GET    | `/api/comments/post/{id}` | Get comments for post |\n| POST   | `/api/comments/post/{id}` | Create comment        |\n\n### Export\n\n| Method | Endpoint                   | Description         |\n| ------ | -------------------------- | ------------------- |\n| GET    | `/api/export/posts.csv`    | Export all posts    |\n| GET    | `/api/export/comments.csv` | Export all comments |\n\n## 🏗️ Project Structure\n\n```text\nx-blog/\n├── backend/                 # FastAPI backend\n│   ├── app/\n│   │   ├── main.py         # Application entry\n│   │   ├── config.py       # Configuration\n│   │   ├── database.py     # Database setup\n│   │   ├── models.py       # SQLAlchemy models\n│   │   ├── schemas.py      # Pydantic schemas\n│   │   ├── crud.py         # Database operations\n│   │   └── routers/        # API routes\n│   ├── tests/              # pytest tests (68 tests)\n│   └── pyproject.toml      # Python config\n│\n├── frontend/               # Next.js frontend\n│   ├── app/\n│   │   ├── page.tsx        # Home page\n│   │   ├── admin/          # Admin dashboard\n│   │   ├── posts/          # Post pages\n│   │   ├── tags/           # Tags page\n│   │   └── about/          # About page\n│   ├── components/         # React components\n│   │   ├── ui/             # shadcn/ui components\n│   │   └── *.tsx\n│   ├── lib/                # Utilities \u0026 API client\n│   ├── types/              # TypeScript types\n│   └── package.json\n│\n├── docs/                   # Documentation\n├── justfile                # Task runner (recommended)\n└── package.json            # Root config (for pnpm workspaces)\n```\n\n## 🧰 Tech Stack\n\n### Backend\n\n- **Framework**: [FastAPI](https://fastapi.tiangolo.com/) - Modern Python web framework\n- **ORM**: [SQLAlchemy](https://www.sqlalchemy.org/) - Database ORM\n- **Database**: SQLite (default), easily switch to PostgreSQL/MySQL\n- **Validation**: [Pydantic](https://docs.pydantic.dev/) - Data validation\n- **Testing**: [pytest](https://pytest.org/) - Python testing with pytest-xdist for parallel execution\n- **Linting**: [ruff](https://docs.astral.sh/ruff/) - Fast Python linter and formatter\n\n### Frontend\n\n- **Framework**: [Next.js 16](https://nextjs.org/) - React framework with App Router\n- **UI**: [shadcn/ui](https://ui.shadcn.com/) - UI components\n- **Styling**: [Tailwind CSS v4](https://tailwindcss.com/) - CSS framework\n- **Forms**: [React Hook Form](https://react-hook-form.com/) - Form handling\n- **Testing**: [Vitest](https://vitest.dev/) - Unit testing\n- **Linting**: [Biome](https://biomejs.dev/) - Fast JS/TS linter and formatter\n\n### DevOps\n\n- **Package Managers**: [uv](https://github.com/astral-sh/uv) (Python), [pnpm](https://pnpm.io/) (Node.js)\n- **Task Runner**: [just](https://github.com/casey/just) - Command runner\n- **Linting**: [ruff](https://docs.astral.sh/ruff/) (Python), [Biome](https://biomejs.dev/) (JS/TS)\n- **Git Hooks**: [prek](https://github.com/astral-sh/prek) - Git hooks manager\n\n## 🧪 Testing\n\n```bash\n# Run all tests\njust test\n\n# Run backend tests (parallel)\njust test-backend\n\n# Run frontend tests\njust test-frontend\n\n# Run tests with coverage\njust test-frontend-coverage\n```\n\n**Test Statistics:**\n\n- Backend: 68 tests (pytest + pytest-xdist)\n- Frontend: 86 tests (Vitest)\n- **Total: 154 tests**\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Run tests to ensure everything passes (`just test`)\n4. Fix any lint issues (`just fix`)\n5. Commit your changes using [Conventional Commits](https://www.conventionalcommits.org/)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## 🚀 Deployment Guide\n\nSee [Deployment Guide](./docs/deployment.md) for detailed instructions on:\n\n- Local development setup\n- Docker production deployment\n- Separated backend/frontend deployment\n- Environment configuration\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nBuilt with ❤️ using FastAPI + Next.js\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpplmx%2Fx-blog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpplmx%2Fx-blog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpplmx%2Fx-blog/lists"}