Skip to content

Update documentation #31

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
barisgit merged 2 commits into from
Apr 24, 2025
Merged

Update documentation #31

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3f6cce5
Fix api url to be automatic
barisgit Apr 24, 2025
5befd9a
Update documentation
barisgit Apr 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 12 additions & 7 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,18 +22,22 @@ We welcome contributions! Here's how to get started:
5. Start development server:

```bash
pnpm run dev
pnpm run dev:web
pnpm run dev:backend # Not actually doing anything yet
```

### Problems with tailwind during development

If you encounter problems with tailwind during development, try the following:

```bash
rm -rf node_modules/ .next/
rm -f pnpm-lock.yaml
pnpm install
pnpm run dev
pnpm clean
# or
pnpm fullclean

pnpm i
pnpm run dev:web
pnpm run dev:backend
```

## Reporting Issues
Expand All @@ -52,7 +56,7 @@ pnpm run dev
4. Run tests (when available) and ensure linting passes:

```bash
pnpm run lint
pnpm lint check-types test
```

5. Ensure that build passed and everything is working:
Expand All @@ -68,9 +72,10 @@ pnpm run dev
## Code Style

- Follow existing TypeScript patterns
- Most of types are setup in a way that you can use autocomplete
- Use Prettier formatting
- Add comments for complex logic
- Always use tailwind classes over custom CSS
- Always use tailwind classes over custom CSS, but you can use custom CSS for things that tailwind doesn't support
- Use consistent naming conventions
- Always include types
- Use pnpm as the package manager
Expand Down
96 changes: 56 additions & 40 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,52 +1,60 @@
# NextWiki

![NextWiki Main Page](./assets/nextwiki-home.png)
![NextWiki Main Page Dark](./assets/nextwiki-home-dark.png)

<p align="center">
<a href="https://next-wiki.com" target="_blank">
<img src="https://img.shields.io/badge/Live%20Demo-Visit%20Now-blue?style=for-the-badge&logo=vercel" alt="Live Demo">
</a>
</p>

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

An open-source wiki system built with modern web technologies, inspired by WikiJS. NextWiki provides a flexible, extensible platform for creating and managing knowledge bases.

## 🚀 Features

- **Modern Stack**: Built with Next.js 15, React 19, Drizzle ORM, tRPC, NextAuth, Tailwind CSS, Codemirror, Shadcn UI, and more
- **Version History**: Track changes (in progress)
- **Markdown Support**: Write content using simple Markdown syntax
- **Direct Image Upload**: Upload images directly with paste or drag and drop
- **Syntax Highlighting**: Syntax highlighting for code blocks
- **Page/Folder Moving Functionality**: Move/rename pages and folders to different locations
- **Authentication**: Secure login with credentials or OAuth providers (only password login is implemented for now)
- **Advanced Search**: Full-text and fuzzy search
- **Tags & Categories**: Organize your content effectively (in progress)
- **Tags & Categories**: Organize your content effectively
- **Asset Manager**: Upload, delete, and manage assets (images, videos, PDFs, etc.)
- **Permissions**: Group and granular permission based access control
- **Settings**: Centralized settings for the wiki, manageable by the admin

## 🛠️ Tech Stack

- **Framework**: [Next.js](https://nextjs.org)
- **Framework**: [Next.js](https://nextjs.org) (for the frontend and core features)
- **Backend**: Optional [NestJS](https://nestjs.com) on Fastify (for features like WebSockets, planned for Yjs integration)
- **Database**: PostgreSQL with [Drizzle ORM](https://orm.drizzle.team)
- **API**: Type-safe APIs with [tRPC](https://trpc.io)
- **API**: Type-safe APIs with [tRPC](https://trpc.io) (primarily within Next.js)
- **Authentication**: [NextAuth.js](https://next-auth.js.org)
- **Search**: PostgreSQL full-text search with trigram similarity for fuzzy matching
- **Styling**: Tailwind CSS
- **Deployment**: Compatible with Vercel, Netlify, or self-hosted
- **Monorepo Management**: Turborepo
- **Deployment**: Compatible with Vercel, Netlify, or self-hosted (NestJS backend requires a Node.js environment)

*Note*: Most functionality resides within the Next.js application and can run on serverless platforms like Vercel. The NestJS backend is included to support optional self-hosted WebSocket functionality, anticipating future integration with Yjs for real-time collaboration, without relying on external providers.

## 🔮 Planned Features

- [ ] **Permissions**: Control who can view and edit content
- [ ] **Centralized settings**: Manage your wiki from a central settings page, with everything stored in the database
- [ ] **S3 Asset Storage**: Store assets in S3 or somewhere else
- [ ] **Tags & Categories**: Organize your content effectively
- [ ] **Better version history**: Track changes and revert to previous versions
- [ ] **Real-time Collaboration**: Multiple users can edit pages simultaneously
- [ ] **Typo tolerance**: Fuzzy search with typo tolerance
- [ ] **PDF Upload**: Upload PDFs to the wiki
- [ ] **Video Upload**: Upload videos to the wiki
- [ ] **Audio Upload**: Upload audio to the wiki
- [ ] **Version history**: Track changes and revert to previous versions
- [ ] **Visual editor**: A visual editor for creating and editing pages
- [ ] **Real-time Collaboration**: Multiple users can edit pages simultaneously using Yjs
- [ ] **Better Settings**: Better settings, ability to manage authentication providers, etc.
- [ ] **Different theme support**: Ability to switch between different themes
- [ ] **Import/Export**: Ability to import and export pages from and to other wiki systems

## 📦 Getting Started

### Prerequisites

- Node.js 18+ (pnpm recommended)
- Node.js 18+ (pnpm required)
- PostgreSQL database (or Neon serverless PostgreSQL)

### Installation
Expand All @@ -67,24 +75,25 @@ An open-source wiki system built with modern web technologies, inspired by WikiJ
3. Copy the environment file and configure it:

```bash
cp .env.example .env.local
cp apps/web/.env.example apps/web/.env
cp packages/db/.env.example packages/db/.env
```

Update the values in `.env.local` with your database and authentication settings.
Update the values in `.env` with your database and authentication settings.

4. Set up the database:
4. Set up the database with one of the following commands:

```bash
pnpm run db:setup # Create the database in docker
pnpm run db:setup # Create the database in docker and seed it with example data

pnpm run db:generate # Generate migrations
pnpm run db:migrate # Apply migrations
pnpm run db:docker # Just create the database in docker without seeding it
```

5. Start the development server:

```bash
pnpm run dev
pnpm run dev:web
pnpm run dev:backend
```

6. Open [http://localhost:3000](http://localhost:3000) in your browser to see the wiki.
Expand All @@ -100,35 +109,39 @@ NextWiki includes a powerful search system with several capabilities:
1. Exact vector matching (highest relevance)
2. Title matching (high relevance)
3. Content matching (medium relevance)
4. Similarity matching for typos (lower relevance) _(in progress)_
4. Similarity matching for typos (lower relevance)

When a user clicks a search result, they'll be taken directly to the page with all instances of the search term highlighted, and the view will automatically scroll to the first match.

## Project Structure

This project uses a Turborepo monorepo structure:

```text
├── drizzle/ # Database migrations
├── public/ # Static assets
├── src/
│ ├── app/ # Next.js app router
│ ├── components/ # React components
│ │ ├── auth/ # Authentication components
│ │ ├── layout/ # Layout components
│ │ ├── ui/ # UI components
│ │ └── wiki/ # Wiki-specific components
│ ├── lib/ # Shared libraries
│ │ ├── db/ # Database connection and schema
│ │ ├── utils/ # Utility functions
│ │ ├── services/ # Database service functions (one layer above the drizzle layer)
│ │ └── trpc/ # tRPC routers and procedures
│ └── types/ # TypeScript type definitions
└── ... configuration files
├── apps/
│ ├── backend/ # Optional NestJS backend (Fastify)
│ └── web/ # Next.js frontend application
├── packages/
│ ├── auth/ # Authentication utilities (NextAuth)
│ ├── db/ # Drizzle ORM schema, migrations, and seeding
│ ├── eslint-config/ # Shared ESLint configuration
│ ├── logger/ # Shared logger configuration
│ ├── tailwind-config/ # Shared Tailwind CSS configuration
│ ├── types/ # Shared TypeScript types
│ ├── typescript-config/ # Shared TypeScript configuration
│ └── ui/ # Shared React UI components (Shadcn UI)
├── .github/ # GitHub Actions workflows
├── schema.dbml # Database schema ER diagram
├── assets/ # Static assets like images for README
├── docs/ # Project documentation
└── ... configuration files (pnpm, turbo, prettier, etc.)
```

## Screenshots

![NextWiki Main Page](./assets/nextwiki-home.png)
![NextWiki Main Page Dark](./assets/nextwiki-home-dark.png)
![NextWiki Main Page Admin](./assets/nextwiki-home-admin.png)

![NextWiki Search](./assets/nextwiki-search.png)

Expand All @@ -138,6 +151,9 @@ When a user clicks a search result, they'll be taken directly to the page with a
![NextWiki Browser](./assets/nextwiki-browser.png)
![NextWiki Move Page](./assets/nextwiki-move.png)

![NextWiki Admin Dashboard](./assets/nextwiki-admin-dashboard.png)
![NextWiki Settings](./assets/nextwiki-admin-settings.png)

## 🤝 Contributing

We welcome contributions! Please see our [CONTRIBUTING.md](./CONTRIBUTING.md) guide for details on how to get started. Even non-code contributions like documentation improvements, bug reports, and feature suggestions are appreciated!
Expand Down
104 changes: 25 additions & 79 deletions apps/backend/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,98 +1,44 @@
<p align="center">
<a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo-small.svg" width="120" alt="Nest Logo" /></a>
</p>

[circleci-image]: https://img.shields.io/circleci/build/github/nestjs/nest/master?token=abc123def456
[circleci-url]: https://circleci.com/gh/nestjs/nest

<p align="center">A progressive <a href="http://nodejs.org" target="_blank">Node.js</a> framework for building efficient and scalable server-side applications.</p>
<p align="center">
<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/l/@nestjs/core.svg" alt="Package License" /></a>
<a href="https://www.npmjs.com/~nestjscore" target="_blank"><img src="https://img.shields.io/npm/dm/@nestjs/common.svg" alt="NPM Downloads" /></a>
<a href="https://circleci.com/gh/nestjs/nest" target="_blank"><img src="https://img.shields.io/circleci/build/github/nestjs/nest/master" alt="CircleCI" /></a>
<a href="https://discord.gg/G7Qnnhy" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
<a href="https://opencollective.com/nest#backer" target="_blank"><img src="https://opencollective.com/nest/backers/badge.svg" alt="Backers on Open Collective" /></a>
<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://opencollective.com/nest/sponsors/badge.svg" alt="Sponsors on Open Collective" /></a>
<a href="https://paypal.me/kamilmysliwiec" target="_blank"><img src="https://img.shields.io/badge/Donate-PayPal-ff3f59.svg" alt="Donate us"/></a>
<a href="https://opencollective.com/nest#sponsor" target="_blank"><img src="https://img.shields.io/badge/Support%20us-Open%20Collective-41B883.svg" alt="Support us"></a>
<a href="https://twitter.com/nestframework" target="_blank"><img src="https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow" alt="Follow us on Twitter"></a>
</p>
<!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)
[![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->

## Description

[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository.

## Project setup
# NextWiki - Backend Application

```bash
$ pnpm install
```
This directory contains the optional NestJS (using Fastify) backend application for the NextWiki project.

## Compile and run the project

```bash
# development
$ pnpm run start
Its primary purpose is to provide WebSocket support for features like real-time collaboration (planned Yjs integration) for users who prefer self-hosting this capability instead of relying on external providers.

# watch mode
$ pnpm run start:dev
**Note:** This backend is *not* required for the core functionality of NextWiki, which resides in the `apps/web` Next.js application.

# production mode
$ pnpm run start:prod
```
For a complete overview of the project structure, features, and setup instructions, please refer to the [root README.md](../../README.md).

## Run tests
## Getting Started

```bash
# unit tests
$ pnpm run test
### Prerequisites

# e2e tests
$ pnpm run test:e2e
Ensure you have installed dependencies from the root of the monorepo:

# test coverage
$ pnpm run test:cov
```bash
# Run from the project root
pnpm install
```

## Deployment

When you're ready to deploy your NestJS application to production, there are some key steps you can take to ensure it runs as efficiently as possible. Check out the [deployment documentation](https://docs.nestjs.com/deployment) for more information.
### Running the Development Server

If you are looking for a cloud-based platform to deploy your NestJS application, check out [Mau](https://mau.nestjs.com), our official platform for deploying NestJS applications on AWS. Mau makes deployment straightforward and fast, requiring just a few simple steps:
To run the development server for this specific application (with hot-reloading):

```bash
$ pnpm install -g @nestjs/mau
$ mau deploy
# Run from the project root
pnpm run dev:backend
```

With Mau, you can deploy your application in just a few clicks, allowing you to focus on building features rather than managing infrastructure.
### Other Commands

## Resources

Check out a few resources that may come in handy when working with NestJS:

- Visit the [NestJS Documentation](https://docs.nestjs.com) to learn more about the framework.
- For questions and support, please visit our [Discord channel](https://discord.gg/G7Qnnhy).
- To dive deeper and get more hands-on experience, check out our official video [courses](https://courses.nestjs.com/).
- Deploy your application to AWS with the help of [NestJS Mau](https://mau.nestjs.com) in just a few clicks.
- Visualize your application graph and interact with the NestJS application in real-time using [NestJS Devtools](https://devtools.nestjs.com).
- Need help with your project (part-time to full-time)? Check out our official [enterprise support](https://enterprise.nestjs.com).
- To stay in the loop and get updates, follow us on [X](https://x.com/nestframework) and [LinkedIn](https://linkedin.com/company/nestjs).
- Looking for a job, or have a job to offer? Check out our official [Jobs board](https://jobs.nestjs.com).

## Support

Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).

## Stay in touch
```bash
# Run from the project root

- Author - [Kamil Myśliwiec](https://twitter.com/kammysliwiec)
- Website - [https://nestjs.com](https://nestjs.com/)
- Twitter - [@nestframework](https://twitter.com/nestframework)
# Compile for production
pnpm run build:backend

## License
# Start production build
pnpm run start:backend

Nest is [MIT licensed](https://github.com/nestjs/nest/blob/master/LICENSE).
# Run tests (unit & e2e)
pnpm run test:backend
```
1 change: 0 additions & 1 deletion apps/web/.env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@
DATABASE_URL=postgresql://user:password@localhost:5432/nextwiki

# API
NEXT_PUBLIC_API_URL=http://localhost:3000/api/trcp
NEXT_PUBLIC_WS_URL=

# NextAuth
Expand Down
Loading
Loading