mirror of
https://github.com/suitenumerique/docs
synced 2026-04-21 13:37:20 +00:00
0fca6db79c
## Purpose integrate Find to Docs ## Proposal - [x] ✨ add a `useSeachDocs` hook in charged of calling the search endpoint. - [x] ✨ add a optional `path` param to the `search` route. This param represents the parent document path in case of a sub-documents (descendants) search. - [x] ⚡️return Indexer results directly without DB calls to retrieve the Document objects. All informations necessary for display are indexed in Find. We can skip the DB calls and improve performance. - [x] ♻️ refactor react `DocSearchContent` components. `DocSearchContent` and `DocSearchSubContent` are now merged a unique component handling all search scenarios and relying on the unique `search` route. - [x] 🔥remove pagination logic in the Indexer. Removing the DB calls also removes the DRF queryset object which handles the pagination. Also we consider pagination not to be necessary for search v1. - [x] 🔥remove the `document/<document_id>/descendants` route. This route is not used anymore. The logic of finding the descendants are moved to the internal `_list_descendants` method. This method is based on the parent `path` instead of the parent `id` which has some consequence about the user access management. Relying on the path prevents the use of the `self.get_object()` method which used to handle the user access logic. - [x] ✨handle fallback logic on DRF based title search in case of non-configured, badly configured or failing at run time indexer. - [x] ✨handle language extension in `title` field. Find returns titles with a language extension (ex: `{ title.fr: "rapport d'activité" }` instead of `{ "title": "rapport d'activité" }`. - [x] 🔧 add a `common.test` file to allow running the tests without docker - [x] ♻️ rename `SearchIndexer` -> `FindDocumentIndexer`. This class has to do with Find in particular and the convention is more coherent with `BaseDocumentIndexer` - [x] ♻️ rename `SEARCH_INDEXER_URL` -> `INDEXING_URL` and `SEARCH_INDEXER_QUERY_URL` -> `SEARCH_URL`. I found the original names very confusing. - [x] 🔧 update the environment variables to activate the FindDocumentIndexer. - [x] ✨automate the generation of encryption key during bootstrap. OIDC_STORE_REFRESH_TOKEN_KEY is a mandatory secret key. We can not push it on Github and we want any contributor to be able to run the app by only running the `make bootstrap`. We chose to generate and wright it into the `common.local` during bootstrap. ## 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 (if noticeable change) - [x] I have added corresponding tests for new features or bug fixes (if applicable) --------- Signed-off-by: charles <charles.englebert@protonmail.com>
245 lines
6.4 KiB
Markdown
245 lines
6.4 KiB
Markdown
<p align="center">
|
|
<a href="https://github.com/suitenumerique/docs">
|
|
<img alt="Docs" src="/docs/assets/banner-docs.png" width="100%" />
|
|
</a>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="https://github.com/suitenumerique/docs/stargazers/">
|
|
<img src="https://img.shields.io/github/stars/suitenumerique/docs" alt="">
|
|
</a>
|
|
<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"/>
|
|
</a>
|
|
<a href="https://github.com/suitenumerique/docs/blob/main/LICENSE">
|
|
<img alt="MIT License" src="https://img.shields.io/github/license/suitenumerique/docs"/>
|
|
</a>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="https://matrix.to/#/#docs-official:matrix.org">Chat on Matrix</a> •
|
|
<a href="/docs/">Documentation</a> •
|
|
<a href="#try-docs">Try Docs</a> •
|
|
<a href="mailto:docs@numerique.gouv.fr">Contact us</a>
|
|
</p>
|
|
|
|
# La Suite Docs: Collaborative Text Editing
|
|
|
|
**Docs, where your notes can become knowledge through live collaboration.**
|
|
|
|
Docs is an open-source collaborative editor that helps teams write, organize, and share knowledge together - in real time.
|
|
|
|
|
|
|
|
|
|
## What is Docs?
|
|
|
|
Docs is an open-source alternative to tools like Notion or Google Docs, focused on:
|
|
|
|
- Real-time collaboration
|
|
- Clean, structured documents
|
|
- Knowledge organization
|
|
- Data ownership & self-hosting
|
|
|
|
***Built for public organizations, companies, and open communities.***
|
|
|
|
## Why use Docs?
|
|
|
|
### Writing
|
|
|
|
- Rich-text & Markdown editing
|
|
- Slash commands & block system
|
|
- Beautiful formatting
|
|
- Offline editing
|
|
- Optional AI writing helpers (rewrite, summarize, translate, fix typos)
|
|
|
|
### Collaboration
|
|
|
|
- Live cursors & presence
|
|
- Comments & sharing
|
|
- Granular access control
|
|
|
|
### Knowledge management
|
|
|
|
- Subpages & hierarchy
|
|
- Searchable content
|
|
|
|
### Export/Import & interoperability
|
|
|
|
- Import to `.docx` and `.md`
|
|
- Export to `.docx`, `.odt`, `.pdf`
|
|
|
|
## Try Docs
|
|
|
|
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
|
|
```
|
|
|
|
> If you encounter permission errors, you may need to use `sudo`, or add your user to the `docker` group.
|
|
|
|
### Bootstrap the project
|
|
|
|
The easiest way to start is using GNU Make:
|
|
|
|
```bash
|
|
make bootstrap FLUSH_ARGS='--no-input'
|
|
```
|
|
|
|
This builds the `app-dev` and `frontend-dev` containers, installs dependencies, runs database migrations, and compiles translations.
|
|
|
|
It is recommended to run this command after pulling new code.
|
|
|
|
Start services:
|
|
|
|
```bash
|
|
make run
|
|
```
|
|
|
|
Open <https://localhost:3000>
|
|
|
|
Default credentials (development only):
|
|
|
|
```md
|
|
username: impress
|
|
password: impress
|
|
```
|
|
|
|
### Frontend development mode
|
|
|
|
For frontend work, running outside Docker is often more convenient:
|
|
|
|
```bash
|
|
make frontend-development-install
|
|
make run-frontend-development
|
|
```
|
|
|
|
### Backend only
|
|
|
|
Starting all services except the frontend container:
|
|
|
|
```bash
|
|
make run-backend
|
|
```
|
|
|
|
### Tests & Linting
|
|
|
|
```bash
|
|
make frontend-test
|
|
make frontend-lint
|
|
```
|
|
|
|
Backend tests can be run without docker. This is useful to configure PyCharm or VSCode to do it.
|
|
Removing docker for testing requires to overwrite some URL and port values that are different in and out of
|
|
Docker. `env.d/development/common` contains all variables, some of them having to be overwritten by those in
|
|
`env.d/development/common.test`.
|
|
|
|
### Demo content
|
|
|
|
Create a basic demo site:
|
|
|
|
```bash
|
|
make demo
|
|
```
|
|
|
|
### More Make targets
|
|
|
|
To check all available Make rules:
|
|
|
|
```bash
|
|
make help
|
|
```
|
|
|
|
### Django admin
|
|
|
|
Create a superuser:
|
|
|
|
```bash
|
|
make superuser
|
|
```
|
|
|
|
Admin UI: <http://localhost:8071/admin>
|
|
|
|
## Contributing
|
|
|
|
This project is community-driven and PRs are welcome.
|
|
|
|
- [Contribution guide](CONTRIBUTING.md)
|
|
- [Translations](https://crowdin.com/project/lasuite-docs)
|
|
- [Chat with us!](https://matrix.to/#/#docs-official:matrix.org)
|
|
|
|
## Roadmap
|
|
|
|
Curious where Docs is headed?
|
|
|
|
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.
|
|
|
|
## Credits ❤️
|
|
|
|
### Stack
|
|
|
|
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/).
|
|
|
|
---
|
|
|
|
### Gov ❤️ open source
|
|
|
|
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.
|
|
|
|
<p align="center">
|
|
<img src="/docs/assets/europe_opensource.png" width="50%"/ alt="Europe Opensource">
|
|
</p>
|