Skip to content

Commit d1a3519

Browse files
actuallypavactuallypav
authored
📝(docs) improve readme and add documentation hub (#1870)
## Purpose This pull request improves the project’s documentation entry points and overall readability to make Docs more approachable for new users and contributors. While reviewing the repository, I noticed that the project highlights documentation and Markdown support, but the front-page README contained several Markdown syntax issues and inconsistencies. This made the landing experience feel less polished than the quality of the project itself. The goal of this change is to provide a cleaner, more consistent, and more professional first impression. Please let me know and I can apply any changes, or edit other .md files as needed! ## Proposal - Rewrite the root README to be tighter, easier to scan, and more user-facing - Add a documentation landing page at `/docs/README.md` with a structured table of contents - Introduce `docs/instances.md` to list public Docs instances ## External contributions Thank you for your contribution! 🎉 Please ensure the following items are checked before submitting your pull request: - [x] I have read and followed the [contributing guidelines](https://github.com/suitenumerique/docs/blob/main/CONTRIBUTING.md) - [x] I have read and agreed to the [Code of Conduct](https://github.com/suitenumerique/docs/blob/main/CODE_OF_CONDUCT.md) - [x] I have signed off my commits with `git commit --signoff` (DCO compliance) - [x] I have signed my commits with my SSH or GPG key (`git commit -S`) - [x] My commit messages follow the required format: `<gitmoji>(type) title description` - [x] I have added a changelog entry under `## [Unreleased]` section - [x] I have not added tests because this PR only contains documentation changes --------- Signed-off-by: actuallypav <61046893+actuallypav@users.noreply.github.com>
1 parent 03ea6b2 commit d1a3519

4 files changed

Lines changed: 262 additions & 130 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@ and this project adheres to
66

77
## [Unreleased]
88

9+
### Changed
10+
11+
- 📝(docs) improve README and add documentation hub #1870
12+
913
## [v4.6.0] - 2026-03-03
1014

1115
### Added

‎README.md‎

Lines changed: 142 additions & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -3,226 +3,238 @@
33
<img alt="Docs" src="/docs/assets/banner-docs.png" width="100%" />
44
</a>
55
</p>
6+
67
<p align="center">
78
<a href="https://github.com/suitenumerique/docs/stargazers/">
89
<img src="https://img.shields.io/github/stars/suitenumerique/docs" alt="">
910
</a>
10-
<a href='https://github.com/suitenumerique/docs/blob/main/CONTRIBUTING.md'><img alt='PRs Welcome' src='https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=shields'/></a>
11-
<img alt="GitHub commit activity" src="https://img.shields.io/github/commit-activity/m/suitenumerique/docs"/>
12-
<img alt="GitHub closed issues" src="https://img.shields.io/github/issues-closed/suitenumerique/docs"/>
11+
<a href="https://github.com/suitenumerique/docs/blob/main/CONTRIBUTING.md">
12+
<img alt="PRs Welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg"/>
13+
</a>
1314
<a href="https://github.com/suitenumerique/docs/blob/main/LICENSE">
1415
<img alt="MIT License" src="https://img.shields.io/github/license/suitenumerique/docs"/>
15-
</a>
16+
</a>
1617
</p>
18+
1719
<p align="center">
18-
<a href="https://matrix.to/#/#docs-official:matrix.org">
19-
Chat on Matrix
20-
</a> - <a href="/docs/">
21-
Documentation
22-
</a> - <a href="#getting-started-">
23-
Getting started
24-
</a> - <a href="mailto:docs@numerique.gouv.fr">
25-
Reach out
26-
</a>
20+
<a href="https://matrix.to/#/#docs-official:matrix.org">Chat on Matrix</a> •
21+
<a href="/docs/">Documentation</a> •
22+
<a href="#try-docs">Try Docs</a> •
23+
<a href="mailto:docs@numerique.gouv.fr">Contact us</a>
2724
</p>
2825

29-
# La Suite Docs : Collaborative Text Editing
30-
Docs, where your notes can become knowledge through live collaboration.
26+
# La Suite Docs: Collaborative Text Editing
3127

32-
<img src="/docs/assets/docs_live_collaboration_light.gif" width="100%" align="center"/>
28+
**Docs, where your notes can become knowledge through live collaboration.**
3329

34-
## Why use Docs ❓
35-
Docs is a collaborative text editor designed to address common challenges in knowledge building and sharing.
30+
Docs is an open-source collaborative editor that helps teams write, organize, and share knowledge together - in real time.
3631

37-
### Write
38-
* 😌 Get simple, accessible online editing for your team.
39-
* 💅 Create clean documents with beautiful formatting options.
40-
* 🖌️ Focus on your content using either the in-line editor, or [the Markdown syntax](https://www.markdownguide.org/basic-syntax/).
41-
* 🧱 Quickly design your page thanks to the many block types, accessible from the `/` slash commands, as well as keyboard shortcuts.
42-
* 🔌 Write offline! Your edits will be synced once you're back online.
43-
* ✨ 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!
32+
![Live collaboration demo](/docs/assets/docs_live_collaboration_light.gif)
4433

45-
### Work together
46-
* 🤝 Enjoy live editing! See your team collaborate in real time.
47-
* 🔒 Keep your information secure thanks to granular access control. Only share with the right people.
48-
* 📑 Export your content in multiple formats (`.odt`, `.docx`, `.pdf`) with customizable templates.
49-
* 📚 Turn your team's collaborative work into organized knowledge with Subpages.
5034

51-
### Self-host
35+
## What is Docs?
5236

53-
#### 🚀 Docs is easy to install on your own servers
54-
We use Kubernetes for our [production instance](https://docs.numerique.gouv.fr/) but also support Docker Compose. The community contributed a couple other methods (Nix, YunoHost etc.) check out the [docs](/docs/installation/README.md) to get detailed instructions and examples.
37+
Docs is an open-source alternative to tools like Notion or Google Docs, focused on:
5538

56-
#### 🌍 Known instances
57-
We hope to see many more, here is an incomplete list of public Docs instances. Feel free to make a PR to add ones that are not listed below🙏
39+
- Real-time collaboration
40+
- Clean, structured documents
41+
- Knowledge organization
42+
- Data ownership & self-hosting
5843

59-
| Url | Org | Public |
60-
| --- | --- | ------- |
61-
| [docs.numerique.gouv.fr](https://docs.numerique.gouv.fr/) | DINUM | French public agents working for the central administration and the extended public sphere. ProConnect is required to login in or sign up|
62-
| [docs.suite.anct.gouv.fr](https://docs.suite.anct.gouv.fr/) | ANCT | French public agents working for the territorial administration and the extended public sphere. ProConnect is required to login in or sign up|
63-
| [notes.demo.opendesk.eu](https://notes.demo.opendesk.eu) | ZenDiS | Demo instance of OpenDesk. Request access to get credentials |
64-
| [notes.liiib.re](https://notes.liiib.re/) | lasuite.coop | Free and open demo to all. Content and accounts are reset after one month |
65-
| [docs.federated.nexus](https://docs.federated.nexus/) | federated.nexus | Public instance, but you have to [sign up for a Federated Nexus account](https://federated.nexus/register/). |
66-
| [docs.demo.mosacloud.eu](https://docs.demo.mosacloud.eu/) | mosa.cloud | Demo instance of mosa.cloud, a dutch company providing services around La Suite apps. |
44+
***Built for public organizations, companies, and open communities.***
6745

68-
#### ⚠️ Advanced features
69-
For some advanced features (ex: Export as PDF) Docs relies on XL packages from BlockNote. These are licenced under GPL and are not MIT compatible. You can perfectly use Docs without these packages by setting the environment variable `PUBLISH_AS_MIT` to true. That way you'll build an image of the application without the features that are not MIT compatible. Read the [environment variables documentation](/docs/env.md) for more information.
46+
## Why use Docs?
7047

71-
## Getting started 🔧
48+
### Writing
7249

73-
### Test it
50+
- Rich-text & Markdown editing
51+
- Slash commands & block system
52+
- Beautiful formatting
53+
- Offline editing
54+
- Optional AI writing helpers (rewirite, summarize, translate, fix typos)
7455

75-
You can test Docs on your browser by visiting this [demo document](https://docs.la-suite.eu/docs/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/)
56+
### Collaboration
7657

77-
### Run Docs locally
58+
- Live cursors & presence
59+
- Comments & sharing
60+
- Granular access control
7861

79-
> ⚠️ 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.
62+
### Knowledge management
8063

81-
**Prerequisite**
64+
- Subpages & hierarchy
65+
- Searchable content
8266

83-
Make sure you have a recent version of Docker and [Docker Compose](https://docs.docker.com/compose/install) installed on your laptop, then type:
67+
### Export/Import & interoperability
8468

85-
```shellscript
86-
$ docker -v
69+
- Import to `.docx` and `.md`
70+
- Export to `.docx`, `.odt`, `.pdf`
8771

88-
Docker version 20.10.2, build 2291f61
72+
## Try Docs
8973

90-
$ docker compose version
74+
Experience Docs instantly - no installation required.
9175

92-
Docker Compose version v2.32.4
93-
```
76+
- 🔗 [Open a live demo document][demo]
77+
- 🌍 [Browse public instances][instances]
9478

95-
> ⚠️ You may need to run the following commands with `sudo`, but this can be avoided by adding your user to the local `docker` group.
79+
[demo]: https://docs.la-suite.eu/docs/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/
80+
[instances]: /docs/instances.md
9681

97-
**Project bootstrap**
82+
## Self-hosting
9883

99-
The easiest way to start working on the project is to use [GNU Make](https://www.gnu.org/software/make/):
84+
Docs supports Kubernetes, Docker Compose, and community-provided methods such as Nix and YunoHost.
10085

101-
```shellscript
102-
$ make bootstrap FLUSH_ARGS='--no-input'
103-
```
86+
Get started with self-hosting: [Installation guide](/docs/installation/README.md)
10487

105-
This command builds the `app-dev` and `frontend-dev` containers, 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.
88+
> [!WARNING]
89+
> Some advanced features (for example: `Export as PDF`) rely on XL packages from Blocknote.
90+
> These packages are licensed under GPL and are **not MIT-compatible**
91+
>
92+
> You can run Docs **without these packages** by building with:
93+
>
94+
> ```bash
95+
> PUBLISH_AS_MIT=true
96+
> ```
97+
>
98+
> This builds an image of Docs without non-MIT features.
99+
>
100+
> More details can be found in [environment variables](/docs/env.md)
106101
107-
Your Docker services should now be up and running 🎉
102+
## Local Development (for contributors)
108103
109-
You can access the project by going to <http://localhost:3000>.
104+
Run Docs locally for development and testing.
110105
111-
You will be prompted to log in. The default credentials are:
106+
> [!WARNING]
107+
> This setup is intended **for development and testing only**.
108+
> It uses Minio as an S3-compatible storage backend, but any S3-compatible service can be used.
112109
113-
```
114-
username: impress
115-
password: impress
116-
```
110+
### Prerequisites
111+
112+
- Docker
113+
- Docker Compose
114+
- GNU Make
117115
118-
📝 Note that if you need to run them afterwards, you can use the eponymous Make rule:
116+
Verify installation:
119117
120-
```shellscript
121-
$ make run
118+
```bash
119+
docker -v
120+
docker compose version
122121
```
123122
124-
⚠️ For the frontend developer, it is often better to run the frontend in development mode locally.
123+
> If you encounounter permission errors, you may need to use `sudo`, or add your user to the `docker` group.
125124
126-
To do so, install the frontend dependencies with the following command:
125+
### Bootstrap the project
127126

128-
```shellscript
129-
$ make frontend-development-install
127+
The easiest way to start is using GNU Make:
128+
129+
```bash
130+
make bootstrap FLUSH_ARGS='--no-input'
130131
```
131132

132-
And run the frontend locally in development mode with the following command:
133+
This builds the `app-dev` and `fronted-dev` containers, installs dependencies, runs database migrations, and compiles translations.
134+
135+
It is recommend to run this command after pulling new code.
136+
137+
Start services:
133138

134-
```shellscript
135-
$ make run-frontend-development
139+
```bash
140+
make run
136141
```
137142

138-
To start all the services, except the frontend container, you can use the following command:
143+
Open <https://localhost:3000>
139144

140-
```shellscript
141-
$ make run-backend
145+
Default credentials (development only):
146+
147+
```md
148+
username: impress
149+
password: impress
142150
```
143151

144-
To execute frontend tests & linting only
145-
```shellscript
146-
$ make frontend-test
147-
$ make frontend-lint
152+
### Frontend development mode
153+
154+
For frontend work, running outside Docker is often more convenient:
155+
156+
```bash
157+
make frontend-development-install
158+
make run-frontend-development
148159
```
149160

150-
**Adding content**
161+
### Backend only
151162

152-
You can create a basic demo site by running this command:
163+
Starting all services except the frontend container:
153164

154-
```shellscript
155-
$ make demo
165+
```bash
166+
make run-backend
156167
```
157168

158-
Finally, you can check all available Make rules using this command:
169+
### Tests & Linting
159170

160-
```shellscript
161-
$ make help
171+
```bash
172+
make frontend-test
173+
make frontend-lint
162174
```
163175

164-
**Django admin**
176+
### Demo content
177+
178+
Create a basic demo site:
165179

166-
You can access the Django admin site at:
180+
```bash
181+
make demo
182+
```
167183

168-
<http://localhost:8071/admin>.
184+
### More Make targets
169185

170-
You first need to create a superuser account:
186+
To check all available Make rules:
171187

172-
```shellscript
173-
$ make superuser
188+
```bash
189+
make help
174190
```
175191

176-
## Feedback 🙋‍♂️🙋‍♀️
192+
### Django admin
177193

178-
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).
194+
Create a superuser:
179195

180-
## Roadmap 💡
196+
```bash
197+
make superuser
198+
```
181199

182-
Want to know where the project is headed? [🗺️ Checkout our roadmap](https://github.com/orgs/numerique-gouv/projects/13/views/11)
200+
Admin UI: <http://localhost:8071/admin>
183201

184-
## License 📝
202+
## Contributing
185203

186-
This work is released under the MIT License (see [LICENSE](https://github.com/suitenumerique/docs/blob/main/LICENSE)).
204+
This project is community-driven and PRs are welcome.
187205

188-
While Docs is a public-driven initiative, our license choice is an invitation for private sector actors to use, sell and contribute to the project.
206+
- [Contribution guide](CONTRIBUTING.md)
207+
- [Translations](https://crowdin.com/project/lasuite-docs)
208+
- [Chat with us!](https://matrix.to/#/#docs-official:matrix.org)
189209

190-
## Contributing 🙌
210+
## Roadmap
191211

192-
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.
212+
Curious where Docs is headed?
193213

194-
You can help us with translations on [Crowdin](https://crowdin.com/project/lasuite-docs).
214+
Explore upcoming features, priorities and long-term direction on our [public roadmap](https://docs.numerique.gouv.fr/docs/d1d3788e-c619-41ff-abe8-2d079da2f084/).
195215

196-
If you intend to make pull requests, see [CONTRIBUTING](https://github.com/suitenumerique/docs/blob/main/CONTRIBUTING.md) for guidelines.
216+
## License 📝
197217

198-
## Directory structure:
218+
This work is released under the MIT License (see [LICENSE](https://github.com/suitenumerique/docs/blob/main/LICENSE)).
199219

200-
```markdown
201-
docs
202-
├── bin - executable scripts or binaries that are used for various tasks, such as setup scripts, utility scripts, or custom commands.
203-
├── crowdin - for crowdin translations, a tool or service that helps manage translations for the project.
204-
├── docker - Dockerfiles and related configuration files used to build Docker images for the project. These images can be used for development, testing, or production environments.
205-
├── docs - documentation for the project, including user guides, API documentation, and other helpful resources.
206-
├── env.d/development - environment-specific configuration files for the development environment. These files might include environment variables, configuration settings, or other setup files needed for development.
207-
├── gitlint - configuration files for `gitlint`, a tool that enforces commit message guidelines to ensure consistency and quality in commit messages.
208-
├── playground - experimental or temporary code, where developers can test new features or ideas without affecting the main codebase.
209-
└── src - main source code directory, containing the core application code, libraries, and modules of the project.
210-
```
220+
While Docs is a public-driven initiative, our license choice is an invitation for private sector actors to use, sell and contribute to the project.
211221

212222
## Credits ❤️
213223

214224
### Stack
215225

216-
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!
226+
Docs is built on top of [Django Rest Framework](https://www.django-rest-framework.org/), [Next.js](https://nextjs.org/), [ProseMirror](https://prosemirror.net/), [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!
217227

218-
We are proud sponsors of [BlockNotejs](https://www.blocknotejs.org/) and [Yjs](https://yjs.dev/).
228+
We are proud sponsors of [BlockNotejs](https://www.blocknotejs.org/) and [Yjs](https://yjs.dev/).
219229

230+
---
220231

221232
### Gov ❤️ open source
222-
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/)).
223233

224-
We are always looking for new public partners (we are currently onboarding the Netherlands 🇳🇱🧀), feel free to [reach out](mailto:docs@numerique.gouv.fr) if you are interested in using or contributing to Docs.
234+
Docs is the result of a joint initiative led by the French 🇫🇷 ([DINUM](https://www.numerique.gouv.fr/dinum/)) Government and German 🇩🇪 government ([ZenDiS](https://zendis.de/)).
235+
236+
We are always looking for new public partners (we are currently onboarding the Netherlands 🇳🇱), feel free to [contact us](mailto:docs@numerique.gouv.fr) if you are interested in using or contributing to Docs.
225237

226238
<p align="center">
227-
<img src="/docs/assets/europe_opensource.png" width="50%"/>
239+
<img src="/docs/assets/europe_opensource.png" width="50%"/ alt="Europe Opensource">
228240
</p>

0 commit comments

Comments
 (0)