Skip to content

📝(doc) Slight improvement of README.md #848

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

Closed
wants to merge 1 commit into from
+43 −39
Closed

📝(doc) Slight improvement of README.md #848

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
82 changes: 43 additions & 39 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -5,7 +5,9 @@
</p>

<p align="center">
Welcome to Docs! The open source document editor where your notes can become knowledge through live collaboration
Welcome to Docs!<br>
Docs is an open-source document editor, where your notes can become knowledge through live collaboration.<br>
It offers a scalable and secure alternative to tools such as Notion, Outline, or Confluence.
</p>

<p align="center">
@@ -22,46 +24,48 @@ Welcome to Docs! The open source document editor where your notes can become kno

<img src="/docs/assets/docs_live_collaboration_light.gif" width="100%" align="center"/>

## Why use Docs ❓

⚠️ **Note that Docs provides docs/pdf exporters by loading [two BlockNote packages](https://github.com/suitenumerique/docs/blob/main/src/frontend/apps/impress/package.json#L22C7-L23C53), which we use under the AGPL-3.0 licence. Until we comply with the terms of this license, we recommend that you don't run Docs as a commercial product, unless you are willing to sponsor [BlockNote](https://github.com/TypeCellOS/BlockNote).**
## Why use Docs?

Docs is a collaborative text editor designed to address common challenges in knowledge building and sharing.

### Write
* 😌 Simple collaborative editing without the formatting complexity of markdown
* 🔌 Offline? No problem, keep writing, your edits will get synced when back online
* 💅 Create clean documents with limited but beautiful formatting options and focus on content
* 🧱 Built for productivity (markdown support, many block types, slash commands, keyboard shortcuts).
* ✨ Save time thanks to our AI actions (generate, sum up, correct, translate)

### Collaborate
* 🤝 Collaborate with your team in real time
* 🔒 Granular access control to ensure your information is secure and only shared with the right people
* 📑 Professional document exports in multiple formats (.odt, .doc, .pdf) with customizable templates
* 📚 Built-in wiki functionality to turn your team's collaborative work into organized knowledge `ETA 02/2025`
* 😌 Get simple, accessible online editing for your team.
* 💅 Create clean documents with beautiful formatting options.
* 🖌️ Focus on your content using either the in-line editor, or [the Markdown syntax](https://www.markdownguide.org/basic-syntax/).
* 🧱 Quickly design your page thanks to the many block types, accessible from the `/` slash commands, as well as keyboard shortcuts.
* 🔌 Write offline! Your edits will be synced once you're back online.
* ✨ Save time thanks to our AI actions, such as rephrasing, summarizing, fixing typos, translating, etc. You can even turn your selected text into a prompt!

### Work together
* 🤝 Enjoy live editing! See your team collaborate in real time.
* 🔒 Keep your information secure thanks to granular access control. Only share with the right people.
* 📑 Export your content in multiple formats (`.odt`, `.docx`, `.pdf`) with customizable templates.
* 📚 _Coming soon! Built-in wiki functionality to turn your team's collaborative work into organized knowledge._

> ⚠️ **Note: The docx/pdf exporters rely on [packages Blocknote project](https://github.com/suitenumerique/docs/blob/main/src/frontend/apps/impress/package.json#L22C7-L23C53), which are under the AGPL-3.0 licence. Because the Docs project uses the MIT license, we recommend that you do not run Docs as a commercial product -- unless you are willing to sponsor [BlockNote](https://github.com/TypeCellOS/BlockNote). We are working on complying with the terms of the Blocknote license.**
Copy link
Collaborator

@virgile-dev virgile-dev Apr 14, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey, I've reworked the phrasing for this. As we are working on this : #845


During Docs installation, you will be prompted if you want to install them or not. Please ensure to fulfill your obligation regarding BlockNoteJS licensing (see https://github.com/TypeCellOS/BlockNote/blob/main/packages/xl-pdf-exporter/LICENSE and https://www.blocknotejs.org/about#partner-with-us).

Also note that Docs works perfectly fine without these export features.```

### Self-host
* 🚀 Easy to install, scalable and secure alternative to Notion, Outline or Confluence
* 🚀 Docs relies on Docker and GNU Make to build a scalable and secure knowledge tool.


## Getting started 🔧

### Test it
### Test Docs right now!
Copy link
Collaborator

@virgile-dev virgile-dev Apr 14, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was recently merged : #812 . Can you update accordingly?


Test Docs on your browser by logging in on this [environment](https://impress-preprod.beta.numerique.gouv.fr/)
You can test Docs on your browser by logging in on this [environment](https://impress-preprod.beta.numerique.gouv.fr/) using the following credentials:

```
email: [email protected]
password: I'd<3ToTestDocs
```

### Run it locally
### Run Docs locally

> ⚠️ Running Docs locally using the methods described below is for testing purposes only. It is based on building Docs using Minio as the S3 storage solution but you can choose any S3 compatible object storage of your choice.
> ⚠️ The methods described below for running Docs locally is **for testing purposes only**. It is based on building Docs using [Minio](https://min.io/) as an S3-compatible storage solution. Of course you can choose any S3-compatible storage solution.
**Prerequisite**

Make sure you have a recent version of Docker and [Docker Compose](https://docs.docker.com/compose/install) installed on your laptop:
Make sure you have a recent version of Docker and [Docker Compose](https://docs.docker.com/compose/install) installed on your laptop, then type:

```shellscript
$ docker -v
@@ -73,7 +77,7 @@ $ docker compose version
Docker Compose version v2.32.4
```

> ⚠️ You may need to run the following commands with sudo but this can be avoided by adding your user to the `docker` group.
> ⚠️ You may need to run the following commands with `sudo`, but this can be avoided by adding your user to the local `docker` group.
**Project bootstrap**

@@ -83,26 +87,26 @@ The easiest way to start working on the project is to use [GNU Make](https://www
$ make bootstrap FLUSH_ARGS='--no-input'
```

This command builds the `app` container, installs dependencies, performs database migrations and compile translations. It's a good idea to use this command each time you are pulling code from the project repository to avoid dependency-related or migration-related issues.
This command builds the `app` container, installs dependencies, performs database migrations and compiles translations. It's a good idea to use this command each time you are pulling code from the project repository to avoid dependency-related or migration-related issues.

Your Docker services should now be up and running 🎉

You can access to the project by going to <http://localhost:3000>.
You can access the project by going to <http://localhost:3000>.

You will be prompted to log in, the default credentials are:
You will be prompted to log in. The default credentials are:

```
username: impress
password: impress
```

📝 Note that if you need to run them afterwards, you can use the eponym Make rule:
> 📝 Note that if you need to run them afterwards, you can use the eponym Make rule:
```shellscript
$ make run
```

⚠️ For the frontend developer, it is often better to run the frontend in development mode locally.
> ⚠️ For frontend developers, it is often better to run the frontend in development mode locally.
To do so, install the frontend dependencies with the following command:

@@ -123,21 +127,21 @@ $ make run-backend
```

**Adding content**
You can create a basic demo site by running:
You can create a basic demo site by running this command:

```shellscript
$ make demo
```

Finally, you can check all available Make rules using:
Finally, you can check all available Make rules using this command:

```shellscript
$ make help
```

**Django admin**

You can access the Django admin site at
You can access the Django admin site at:

<http://localhost:8071/admin>.

@@ -149,7 +153,7 @@ $ make superuser

## Feedback 🙋‍♂️🙋‍♀️

We'd love to hear your thoughts and hear about your experiments, so come and say hi on [Matrix](https://matrix.to/#/#docs-official:matrix.org).
We'd love to hear your thoughts, and hear about your experiments, so come and say hi on [Matrix](https://matrix.to/#/#docs-official:matrix.org).

## Roadmap

@@ -159,17 +163,17 @@ Want to know where the project is headed? [🗺️ Checkout our roadmap](https:/

This work is released under the MIT License (see [LICENSE](https://github.com/suitenumerique/docs/blob/main/LICENSE)).

While Docs is a public driven initiative our licence choice is an invitation for private sector actors to use, sell and contribute to the project.
While Docs is a public-driven initiative, our licence choice is an invitation for private sector actors to use, sell, and contribute to the project.

## Contributing 🙌

This project is intended to be community-driven, so please, do not hesitate to [get in touch](https://matrix.to/#/#docs-official:matrix.org) if you have any question related to our implementation or design decisions.
This project is intended to be community-driven, so please do not hesitate to [get in touch](https://matrix.to/#/#docs-official:matrix.org) if you have any question related to our implementation or design decisions.

You can help us with translations on [Crowdin](https://crowdin.com/project/lasuite-docs).

If you intend to make pull requests see [CONTRIBUTING](https://github.com/suitenumerique/docs/blob/main/CONTRIBUTING.md) for guidelines.
If you intend to make pull requests, see [CONTRIBUTING](https://github.com/suitenumerique/docs/blob/main/CONTRIBUTING.md) for guidelines.

Directory structure:
## Directory structure:

```markdown
docs
@@ -187,13 +191,13 @@ docs

### Stack

Docs is built on top of [Django Rest Framework](https://www.django-rest-framework.org/), [Next.js](https://nextjs.org/), [BlockNote.js](https://www.blocknotejs.org/), [HocusPocus](https://tiptap.dev/docs/hocuspocus/introduction) and [Yjs](https://yjs.dev/).
Docs is built on top of [Django Rest Framework](https://www.django-rest-framework.org/), [Next.js](https://nextjs.org/), [BlockNote.js](https://www.blocknotejs.org/), [HocusPocus](https://tiptap.dev/docs/hocuspocus/introduction) and [Yjs](https://yjs.dev/). We thank the contributors of all these projects for their awesome work!

### Gov ❤️ open source
We are proud sponsors of [BlockNotejs](https://www.blocknotejs.org/) and [Yjs](https://yjs.dev/).

Docs is the result of a joint effort led by the French 🇫🇷🥖 ([DINUM](https://www.numerique.gouv.fr/dinum/)) and German 🇩🇪🥨 governments ([ZenDiS](https://zendis.de/)).
### Gov ❤️ open source

We are proud sponsors of [BlockNotejs](https://www.blocknotejs.org/) and [Yjs](https://yjs.dev/).
Docs is the result of a joint effort led by the French 🇫🇷🥖 ([DINUM](https://www.numerique.gouv.fr/dinum/)) and German 🇩🇪🥨 governments ([ZenDiS](https://zendis.de/)).

We are always looking for new public partners (we are currently onboarding the Netherlands 🇳🇱🧀), feel free to [reach out](mailto:[email protected]) if you are interested in using or contributing to Docs.