From d1a351964699a27150e0f77ad5d5f5c0fa78c4b1 Mon Sep 17 00:00:00 2001 From: pav <61046893+actuallypav@users.noreply.github.com> Date: Thu, 5 Mar 2026 14:55:35 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D(docs)=20improve=20readme=20and=20a?= =?UTF-8?q?dd=20documentation=20hub=20(#1870)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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: `(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> --- CHANGELOG.md | 4 + README.md | 284 ++++++++++++++++++++++++---------------------- docs/README.md | 39 +++++++ docs/instances.md | 77 +++++++++++++ 4 files changed, 268 insertions(+), 136 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/instances.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 50c31b74..b78304a5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ and this project adheres to ## [Unreleased] +### Changed + +- πŸ“(docs) improve README and add documentation hub #1870 + ## [v4.6.0] - 2026-03-03 ### Added diff --git a/README.md b/README.md index 1f12ad35..823e5800 100644 --- a/README.md +++ b/README.md @@ -3,226 +3,238 @@ Docs

+

- PRs Welcome - GitHub commit activity - GitHub closed issues + + PRs Welcome + MIT License - -

-

- - Chat on Matrix - - - Documentation - - - Getting started - - - Reach out

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

+ Chat on Matrix β€’ + Documentation β€’ + Try Docs β€’ + Contact us +

- +# La Suite Docs: Collaborative Text Editing -## Why use Docs ❓ -Docs is a collaborative text editor designed to address common challenges in knowledge building and sharing. +**Docs, where your notes can become knowledge through live collaboration.** -### Write -* 😌 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! +Docs is an open-source collaborative editor that helps teams write, organize, and share knowledge together - in real time. -### 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. -* πŸ“š Turn your team's collaborative work into organized knowledge with Subpages. +![Live collaboration demo](/docs/assets/docs_live_collaboration_light.gif) -### Self-host -#### πŸš€ Docs is easy to install on your own servers -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. +## What is Docs? -#### 🌍 Known instances -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πŸ™ +Docs is an open-source alternative to tools like Notion or Google Docs, focused on: -| Url | Org | Public | -| --- | --- | ------- | -| [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| -| [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| -| [notes.demo.opendesk.eu](https://notes.demo.opendesk.eu) | ZenDiS | Demo instance of OpenDesk. Request access to get credentials | -| [notes.liiib.re](https://notes.liiib.re/) | lasuite.coop | Free and open demo to all. Content and accounts are reset after one month | -| [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/). | -| [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. | +- Real-time collaboration +- Clean, structured documents +- Knowledge organization +- Data ownership & self-hosting -#### ⚠️ Advanced features -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. +***Built for public organizations, companies, and open communities.*** -## Getting started πŸ”§ +## Why use Docs? -### Test it +### Writing -You can test Docs on your browser by visiting this [demo document](https://docs.la-suite.eu/docs/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/) +- Rich-text & Markdown editing +- Slash commands & block system +- Beautiful formatting +- Offline editing +- Optional AI writing helpers (rewirite, summarize, translate, fix typos) -### Run Docs locally +### Collaboration -> ⚠️ 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. +- Live cursors & presence +- Comments & sharing +- Granular access control -**Prerequisite** +### Knowledge management -Make sure you have a recent version of Docker and [Docker Compose](https://docs.docker.com/compose/install) installed on your laptop, then type: +- Subpages & hierarchy +- Searchable content -```shellscript -$ docker -v +### Export/Import & interoperability -Docker version 20.10.2, build 2291f61 +- Import to `.docx` and `.md` +- Export to `.docx`, `.odt`, `.pdf` -$ docker compose version +## Try Docs -Docker Compose version v2.32.4 +Experience Docs instantly - no installation required. + +- πŸ”— [Open a live demo document][demo] +- 🌍 [Browse public instances][instances] + +[demo]: https://docs.la-suite.eu/docs/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/ +[instances]: /docs/instances.md + +## Self-hosting + +Docs supports Kubernetes, Docker Compose, and community-provided methods such as Nix and YunoHost. + +Get started with self-hosting: [Installation guide](/docs/installation/README.md) + +> [!WARNING] +> Some advanced features (for example: `Export as PDF`) rely on XL packages from Blocknote. +> These packages are licensed under GPL and are **not MIT-compatible** +> +> You can run Docs **without these packages** by building with: +> +> ```bash +> PUBLISH_AS_MIT=true +> ``` +> +> This builds an image of Docs without non-MIT features. +> +> More details can be found in [environment variables](/docs/env.md) + +## Local Development (for contributors) + +Run Docs locally for development and testing. + +> [!WARNING] +> This setup is intended **for development and testing only**. +> It uses Minio as an S3-compatible storage backend, but any S3-compatible service can be used. + +### Prerequisites + +- Docker +- Docker Compose +- GNU Make + +Verify installation: + +```bash +docker -v +docker compose version ``` -> ⚠️ You may need to run the following commands with `sudo`, but this can be avoided by adding your user to the local `docker` group. +> If you encounounter permission errors, you may need to use `sudo`, or add your user to the `docker` group. -**Project bootstrap** +### Bootstrap the project -The easiest way to start working on the project is to use [GNU Make](https://www.gnu.org/software/make/): +The easiest way to start is using GNU Make: -```shellscript -$ make bootstrap FLUSH_ARGS='--no-input' +```bash +make bootstrap FLUSH_ARGS='--no-input' ``` -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. +This builds the `app-dev` and `fronted-dev` containers, installs dependencies, runs database migrations, and compiles translations. -Your Docker services should now be up and running πŸŽ‰ +It is recommend to run this command after pulling new code. -You can access the project by going to . - -You will be prompted to log in. The default credentials are: +Start services: +```bash +make run ``` + +Open + +Default credentials (development only): + +```md username: impress password: impress ``` -πŸ“ Note that if you need to run them afterwards, you can use the eponymous Make rule: +### Frontend development mode -```shellscript -$ make run +For frontend work, running outside Docker is often more convenient: + +```bash +make frontend-development-install +make run-frontend-development ``` -⚠️ For the frontend developer, it is often better to run the frontend in development mode locally. +### Backend only -To do so, install the frontend dependencies with the following command: +Starting all services except the frontend container: -```shellscript -$ make frontend-development-install +```bash +make run-backend ``` -And run the frontend locally in development mode with the following command: +### Tests & Linting -```shellscript -$ make run-frontend-development +```bash +make frontend-test +make frontend-lint ``` -To start all the services, except the frontend container, you can use the following command: +### Demo content -```shellscript -$ make run-backend +Create a basic demo site: + +```bash +make demo ``` -To execute frontend tests & linting only -```shellscript -$ make frontend-test -$ make frontend-lint +### More Make targets + +To check all available Make rules: + +```bash +make help ``` -**Adding content** +### Django admin -You can create a basic demo site by running this command: +Create a superuser: -```shellscript -$ make demo +```bash +make superuser ``` -Finally, you can check all available Make rules using this command: +Admin UI: -```shellscript -$ make help -``` +## Contributing -**Django admin** +This project is community-driven and PRs are welcome. -You can access the Django admin site at: +- [Contribution guide](CONTRIBUTING.md) +- [Translations](https://crowdin.com/project/lasuite-docs) +- [Chat with us!](https://matrix.to/#/#docs-official:matrix.org) -. +## Roadmap -You first need to create a superuser account: +Curious where Docs is headed? -```shellscript -$ 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). - -## Roadmap πŸ’‘ - -Want to know where the project is headed? [πŸ—ΊοΈ Checkout our roadmap](https://github.com/orgs/numerique-gouv/projects/13/views/11) +Explore upcoming features, priorities and long-term direction on our [public roadmap](https://docs.numerique.gouv.fr/docs/d1d3788e-c619-41ff-abe8-2d079da2f084/). ## License πŸ“ 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 license 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. - -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. - -## Directory structure: - -```markdown -docs -β”œβ”€β”€ bin - executable scripts or binaries that are used for various tasks, such as setup scripts, utility scripts, or custom commands. -β”œβ”€β”€ crowdin - for crowdin translations, a tool or service that helps manage translations for the project. -β”œβ”€β”€ 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. -β”œβ”€β”€ docs - documentation for the project, including user guides, API documentation, and other helpful resources. -β”œβ”€β”€ 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. -β”œβ”€β”€ gitlint - configuration files for `gitlint`, a tool that enforces commit message guidelines to ensure consistency and quality in commit messages. -β”œβ”€β”€ playground - experimental or temporary code, where developers can test new features or ideas without affecting the main codebase. -└── src - main source code directory, containing the core application code, libraries, and modules of the project. -``` +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. ## Credits ❀️ ### 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/). We thank the contributors of all these projects for their awesome work! +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! -We are proud sponsors of [BlockNotejs](https://www.blocknotejs.org/) and [Yjs](https://yjs.dev/). +We are proud sponsors of [BlockNotejs](https://www.blocknotejs.org/) and [Yjs](https://yjs.dev/). +--- ### Gov ❀️ open source -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:docs@numerique.gouv.fr) if you are interested in using or contributing to Docs. +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/)). + +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.

- + Europe Opensource

diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..f58a492c --- /dev/null +++ b/docs/README.md @@ -0,0 +1,39 @@ +# Docs Documentation + +Welcome to the official documentation for Docs. + +This documentation is organized by topic and audience. +Use the section below to quickly find what you are looking for. + +--- + +## Table of Contents + +- Getting started + - [System requirements](system-requirements.md) + - [Installation overview](installation/README.md) + - [Docker Compose deployment](installation/compose.md) + - [Docker Compose examples](examples/compose/) + - [Kubernetes deployment](installation/kubernetes.md) + - [Helm values examples](examples/helm/) + +- Configuration + - [Environment variables](env.md) + - [Customization](customization.md) + - [Language configuration](languages-configuration.md) + - [Search configuration](search.md) + +- Architecture & design + - [Architecture overview](architecture.md) + - [Architectural Decision Records (ADR)](adr/) + +- Usage & operations + - [Public instances](instances.md) + - [Releases & upgrades](release.md) + - [Troubleshooting](troubleshoot.md) + +- Project & product + - [Roadmap](roadmap.md) + +- Assets + - [Branding & visuals](assets/) diff --git a/docs/instances.md b/docs/instances.md new file mode 100644 index 00000000..99e14359 --- /dev/null +++ b/docs/instances.md @@ -0,0 +1,77 @@ +# 🌍 Public Docs Instances + +This page lists known public instances of **Docs**. + +These instances are operated by different organizations and may have different access policies. +If you run a public instance and would like it listed here, feel free to open a pull request. + +--- + +## πŸ›οΈ Public Organizations + +### docs.numerique.gouv.fr + +**Organization:** DINUM +**Audience:** French public agents working for central administration and extended public sphere +**Access:** ProConnect account required + + +### docs.suite.anct.gouv.fr + +**Organization:** ANCT +**Audience:** French public agents working for territorial administration and extended public sphere +**Access:** ProConnect account required + + +### notes.demo.opendesk.eu + +**Organization:** ZenDiS +**Type:** OpenDesk demo instance +**Access:** Request credentials + + +--- + +## 🏒 Private Sector + +### docs.demo.mosacloud.eu + +**Organization:** mosa.cloud +**Type:** Demo instance + + +### notes.liiib.re + +**Organization:** lasuite.coop +**Access:** Public demo +**Notes:** Content and accounts reset monthly + + +### notes.lasuite.coop + +**Organization:** lasuite.coop +**Access:** Public + + +--- + +## 🀝 NGOs + +### docs.federated.nexus + +**Organization:** federated.nexus +**Access:** Public with account registration + + +--- + +## βž• Add your instance + +To add your instance: + +1. Fork the repository +2. Edit `docs/instances.md` +3. Add your instance following the existing format +4. Open a pull request + +Thank you for helping grow the Docs ecosystem ❀️