Feat: Outline import by NicolasRitouet · Pull Request #1478 · suitenumerique/docs

NicolasRitouet · 2025-10-12T15:02:52Z

Purpose

Add Outline import functionality to allow users to migrate their documentation from Outline by uploading a .zip export file.

Proposal

Add backend API endpoint to handle Outline .zip upload
- Implement Outline export processing service that:
  - Extracts markdown files from the archive
  - Converts markdown content to BlockNote format (Yjs)
  - Preserves document hierarchy and nested documents
  - Handles image attachments by uploading them to object storage
- Add frontend import page at /import/outline
- Fix CSRF token handling in upload request
- Prevent duplicate documents for nested structures (e.g., Doc.md + Doc/ directory)
- Add French translations for the import UI

External contributions

Thank you for your contribution! 🎉

Please ensure the following items are checked before submitting your pull request:

I have read and followed the contributing guidelines
I have read and agreed to the Code of Conduct
I have signed off my commits with git commit --signoff (DCO compliance)
I have signed my commits with my SSH or GPG key (git commit -S)
My commit messages follow the required format: <gitmoji>(type) title description
I have added a changelog entry under ## [Unreleased] section (if noticeable change)
I have added corresponding tests for new features or bug fixes (if applicable)

…kend:\n- Add POST /api/v1.0/outline_import/upload (zip)\n- Parse .md files, create doc tree from folders, rewrite image links to attachments, convert to Yjs via Y-provider\nFrontend:\n- Add /import/outline page with zip file picker + POST\n- Add menu entry 'Import from Outline' in left panel header\n- Add minimal i18n keys (en, fr)

…ous forbidden\n- Authenticated happy path with local image and mocked conversion

…import.py and call from view\n- Keep view thin; service handles zip, images, conversion, attachments\n- Fix imports accordingly

…ject unsafe paths)\n- Ignore __MACOSX and hidden entries\n- Service unit tests (happy path + zip slip)\n- Change API path to /imports/outline/upload and update front + tests

…kNote elements - Convert H4/H5/H6 headings to compatible formats (H4→H3 with marker, H5→bold with arrow, H6→paragraph with bullet) - Convert horizontal rules (---, ***, ___) to [DIVIDER_BLOCK] markers - Preserve task lists formatting for proper checkbox rendering - Add comprehensive unit tests for all conversion cases This ensures Outline exports with all 6 heading levels and other markdown features are properly imported into BlockNote.js which only supports 3 heading levels.

…ted BlockNote elements" This reverts commit b7a7663.

Resolved conflict in translations.json by keeping Outline import translations

- Add CSRF token to Outline import upload request - Fix content save by removing invalid update_fields parameter - Handle nested documents properly to avoid duplicates when a document has child documents (e.g., Doc.md with Doc/ directory)

NicolasRitouet · 2025-10-12T15:13:38Z

In progress:

UI is ugly
attachments are not uploaded
not all content blocks have been tested

StephanMeijer · 2025-10-29T10:31:31Z

src/backend/core/services/outline_import.py

+
+def _upload_attachment(user, doc: models.Document, arcname: str, data: bytes) -> str:
+    """Upload a binary asset into object storage and return its public media URL."""
+    content_type, _ = mimetypes.guess_type(arcname)


What is the library underneath using? Mimetype guessing is not always stable (even when using libmagic it can differ from version/environment).
I would suggest good testing, preferably in different environments if possible.

StephanMeijer · 2025-10-29T10:32:57Z

src/backend/core/services/outline_import.py

+        parts = [p for p in name.split("/") if p]
+        if any(part == ".." for part in parts):
+            raise OutlineImportError("Unsafe path in archive")


Is this always unsafe or only when .. goes beyond the root you are iterating over?

lunika · 2025-11-10T10:18:04Z

src/backend/core/api/imports.py

+        uploaded = request.FILES.get("file")
+        if not uploaded:
+            raise drf.exceptions.ValidationError({"file": "File is required"})
+
+        name = getattr(uploaded, "name", "")
+        if not name.endswith(".zip"):
+            raise drf.exceptions.ValidationError({"file": "Must be a .zip file"})


You should rely on a drf serializer here to validate the input instead of doing it in the view. You can maybe reused the FileUploadSerializer present in the serializer module (src/backend/core/api/serializers.py)

Then once the input validated you have to rely on the malware_detection feature to validate the zip content. But we have to imagine a workflow, this process is async. Once the malware detection ended, the process_outile_zip should start.

lunika · 2025-11-10T10:19:47Z

src/backend/core/api/imports.py

+            # Fail fast if the upload is not a valid zip archive
+            with zipfile.ZipFile(io.BytesIO(content)):
+                pass
+            created_ids = process_outline_zip(request.user, content)


I suggestion to save the uploaded zip on the bucket storage (you can rely on the django storage API). Doing this you can create a celery task to process the file in an async way

lunika · 2025-11-10T10:20:45Z

src/backend/core/services/outline_import.py

+    return f"{settings.MEDIA_BASE_URL}{settings.MEDIA_URL}{key}"
+
+
+def process_outline_zip(user, zip_bytes: bytes) -> list[str]:


With the previous comment made, asking to save the file on the bucket, you can transform this function in a celery task and execute it asynchronously

lunika · 2025-11-10T10:30:05Z

src/backend/core/services/outline_import.py

+        models.DocumentAccess.objects.update_or_create(
+            document=doc,
+            user=user,
+            defaults={"role": models.RoleChoices.OWNER},
+        )


Suggested change

models.DocumentAccess.objects.update_or_create(

document=doc,

user=user,

defaults={"role": models.RoleChoices.OWNER},

)

You have to define an owner access for the user only on the root document. Then the children will inherit from this access.

lunika · 2025-11-10T10:31:03Z

src/backend/core/services/outline_import.py

+                creator=user,
+                title=part,
+                link_reach=models.LinkReachChoices.RESTRICTED,
+            )


Suggested change

)

)

models.DocumentAccess.objects.create(

document=doc,

user=user,

role=models.RoleChoices.OWNER,

)

lunika · 2025-11-10T10:32:05Z

src/backend/core/services/outline_import.py

+        if parent_doc is None:
+            doc = models.Document.add_root(
+                depth=1,
+                creator=user,
+                title=title,
+                link_reach=models.LinkReachChoices.RESTRICTED,
+            )
+        else:
+            doc = parent_doc.add_child(creator=user, title=title)


Suggested change

if parent_doc is None:

doc = models.Document.add_root(

depth=1,

creator=user,

title=title,

link_reach=models.LinkReachChoices.RESTRICTED,

)

else:

doc = parent_doc.add_child(creator=user, title=title)

This is managed in _ensure_dir_documents function. You will probably have duplicated docs at the end

lunika · 2025-11-10T10:32:20Z

src/backend/core/services/outline_import.py

+        models.DocumentAccess.objects.update_or_create(
+            document=doc,
+            user=user,
+            defaults={"role": models.RoleChoices.OWNER},
+        )


Suggested change

models.DocumentAccess.objects.update_or_create(

document=doc,

user=user,

defaults={"role": models.RoleChoices.OWNER},

)

Managed in the _ensure_dir_documents function

lunika · 2025-11-10T10:38:55Z

src/backend/core/services/outline_import.py

+    extra_args = {
+        "Metadata": {
+            "owner": str(user.id),
+            "status": enums.DocumentAttachmentStatus.READY,


Suggested change

"status": enums.DocumentAttachmentStatus.READY,

"status": enums.DocumentAttachmentStatus.PROCESSING,

- Use python-magic instead of mimetypes for reliable MIME detection - Set attachment status to PROCESSING instead of READY (pending malware scan) - Create DocumentAccess only for root documents (children inherit access) - Reorganize imports (stdlib, third-party, django, local) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

… review - Add SessionAuthentication to upload endpoint - Add trailing slash to upload URL for Django compatibility - Register outline_import task in celery autodiscover - Add migration merge for comments feature conflict - Improve import UI with drag-drop, progress states, and translations - Add logging for markdown conversion failures

virgile-dev · 2026-01-29T10:52:54Z

@rl-83 hey ! we need you help figuring out the right UX for this.
This is an awesome contribution. It just needs good UX and polished UI.
Thanks a bunch.

Apply ruff formatting to outline import files and add merge migration to resolve conflict between outline import and template removal migrations. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Fix ruff lint: move imports to top level, fix import sorting, bind loop variables in closures, add noqa for intentional patterns - Fix tests: add trailing slashes to URLs, update to async flow (202 status, mock storage/malware instead of sync processing) - Fix frontend: use @gouvfr-lasuite/cunningham-react instead of @openfun/cunningham-react, fix color token names (brand-* and gray-* instead of primary-* and greyscale-*) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Extract archive processing into _process_archive to properly close the ZipFile via a context manager, preventing resource leaks. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

robin-lecomte · 2026-02-10T12:59:30Z

Hello gentlemen,

Here is my UX proposal.

I suggest reusing the Docs import button, but enhancing it with a dedicated modal that provides users with additional information.

I considered adding a “How to import via Outscale” button that would open a help modal, but I figured people could probably find the information on their own. In the import modal, we already mention that Outscale imports use a ZIP format. Do you think that’s clear enough? I’d like to avoid cluttering the interface with too many tips, especially if we add more import methods in the future.

NicolasRitouet added 13 commits September 13, 2025 07:28

frontend(import-outline): fix baseApiUrl import path

1fd4406

outline-import: run malware scan on uploaded assets

becc514

tests(outline-import): add API tests for upload (.zip) flow\n- Anonym…

9f4fb06

…ous forbidden\n- Authenticated happy path with local image and mocked conversion

refactor(outline-import): move import logic to core/services/outline_…

4f3b62d

…import.py and call from view\n- Keep view thin; service handles zip, images, conversion, attachments\n- Fix imports accordingly

outline-import: reinforce safety and tests\n- Zip Slip protection (re…

fa65c45

…ject unsafe paths)\n- Ignore __MACOSX and hidden entries\n- Service unit tests (happy path + zip slip)\n- Change API path to /imports/outline/upload and update front + tests

Add Outline import API view

cce6c96

Remove legacy Outline import viewset

6146a48

Improve Outline import validation and UI

453b153

Revert "feat(outline-import): Add markdown preprocessing for unsuppor…

06d9c2b

…ted BlockNote elements" This reverts commit b7a7663.

Merge main into feature/outline-import

95fa210

Resolved conflict in translations.json by keeping Outline import translations

NicolasRitouet marked this pull request as draft October 12, 2025 15:03

NicolasRitouet added 3 commits October 12, 2025 17:18

Cleanup imports

538c641

Fix import outline

619b624

add new line

e1f5a13

NicolasRitouet changed the title ~~Feature/outline import~~ Feat: Outline import Oct 12, 2025

es-lint fixes

7d6f055

virgile-dev requested review from lunika and robin-lecomte October 13, 2025 08:57

virgile-dev mentioned this pull request Oct 15, 2025

Import outline notes into docs #1471

Closed

StephanMeijer reviewed Oct 29, 2025

View reviewed changes

lunika reviewed Nov 10, 2025

View reviewed changes

NicolasRitouet and others added 3 commits November 29, 2025 06:20

Merge upstream/main into feature/outline-import

600672d

virgile-dev added the ✏️ Needs design A problem or need has been identified that requires UX design investigation label Jan 29, 2026

virgile-dev added this to LaSuite Docs Jan 29, 2026

virgile-dev moved this to To do in LaSuite Docs Jan 29, 2026

NicolasRitouet and others added 5 commits January 29, 2026 12:42

Merge upstream/main into feature/outline-import

622bcb0

fix(outline-import): fix ruff formatting and migration conflict

e7b541b

Apply ruff formatting to outline import files and add merge migration to resolve conflict between outline import and template removal migrations. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

fix(outline-import): remove local claude settings from branch

686d581

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

fix(outline-import): use context manager for ZipFile

ddf8d6e

Extract archive processing into _process_archive to properly close the ZipFile via a context manager, preventing resource leaks. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

robin-lecomte assigned robin-lecomte and unassigned robin-lecomte Feb 10, 2026

robin-lecomte added ✅ Design approved The PO has approved the design: developers can start implementation and removed ✏️ Needs design A problem or need has been identified that requires UX design investigation labels Feb 10, 2026

virgile-dev moved this from To do to Backlog in LaSuite Docs Mar 9, 2026

		return f"{settings.MEDIA_BASE_URL}{settings.MEDIA_URL}{key}"


		def process_outline_zip(user, zip_bytes: bytes) -> list[str]:

	"status": enums.DocumentAttachmentStatus.READY,
	"status": enums.DocumentAttachmentStatus.PROCESSING,

Conversation

NicolasRitouet commented Oct 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Purpose

Proposal

External contributions

Uh oh!

NicolasRitouet commented Oct 12, 2025

Uh oh!

StephanMeijer Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

virgile-dev commented Jan 29, 2026

Uh oh!

robin-lecomte commented Feb 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

NicolasRitouet commented Oct 12, 2025 •

edited

Loading

StephanMeijer Oct 29, 2025 •

edited

Loading