Skip to content

⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.

feat(web): create a page from an uploaded Markdown file (#613)

Karthik Kulkarnic5508e5d6fbc
diff --git a/apps/web/messages/ar/documents.json b/apps/web/messages/ar/documents.json
index 1b3d6984..fa6e3293 100644
--- a/apps/web/messages/ar/documents.json
+++ b/apps/web/messages/ar/documents.json
@@ -1,6 +1,7 @@
{
"title": "المستندات",
"newDocument": "صفحة جديدة",
+ "uploadMarkdown": "رفع ملف Markdown",
"favoritePages": "المفضلة",
"newSubpage": "إضافة صفحة تحت {title}",
"addSubpage": "إضافة صفحة فرعية",
@@ -79,6 +80,8 @@
"exporting": "جارٍ التحضير…",
"exportFailed": "تعذّر تضمين جميع الملفات المحمية في التصدير. حاول مرة أخرى.",
"exportTooLarge": "تحتوي الصفحة على ملفات محمية كثيرة جدًا أو كبيرة جدًا لتصدير واحد (بحد أقصى 50 ملفًا و100 ميغابايت).",
+ "markdownTooLarge": "ملف Markdown هذا أكبر من أن تستوعبه صفحة واحدة.",
+ "markdownReadFailed": "تعذّرت قراءة ملف Markdown.",
"cancel": "إلغاء",
"publicPages": "عامة",
"privatePages": "خاصة",
diff --git a/apps/web/messages/en/documents.json b/apps/web/messages/en/documents.json
index 818f8f95..7813a689 100644
--- a/apps/web/messages/en/documents.json
+++ b/apps/web/messages/en/documents.json
@@ -1,6 +1,7 @@
{
"title": "Docs",
"newDocument": "New page",
+ "uploadMarkdown": "Upload Markdown",
"favoritePages": "Favorites",
"publicPages": "Public",
"privatePages": "Private",
@@ -135,6 +136,8 @@
"exporting": "Preparing…",
"exportFailed": "The export could not include all protected assets. Try again.",
"exportTooLarge": "This page has too many or too much protected content to export at once (maximum 50 files and 100 MB).",
+ "markdownTooLarge": "This Markdown file is too large for one page.",
+ "markdownReadFailed": "Could not read the Markdown file.",
"cancel": "Cancel",
"linkWorkItem": {
"tab": "Work items",
diff --git a/apps/web/messages/es-ES/documents.json b/apps/web/messages/es-ES/documents.json
index b51546bc..3c25927c 100644
--- a/apps/web/messages/es-ES/documents.json
+++ b/apps/web/messages/es-ES/documents.json
@@ -1,6 +1,7 @@
{
"title": "Documentos",
"newDocument": "Nueva página",
+ "uploadMarkdown": "Subir Markdown",
"favoritePages": "Favoritas",
"publicPages": "Públicas",
"privatePages": "Privadas",
@@ -135,6 +136,8 @@
"exporting": "Preparando…",
"exportFailed": "La exportación no ha podido incluir todos los recursos protegidos. Inténtalo otra vez.",
"exportTooLarge": "Esta página tiene demasiados contenidos protegidos para exportar de golpe (máximo 50 ficheros y 100 MB).",
+ "markdownTooLarge": "Este archivo Markdown es demasiado grande para una sola página.",
+ "markdownReadFailed": "No se pudo leer el archivo Markdown.",
"cancel": "Cancelar",
"linkWorkItem": {
"tab": "Elementos de trabajo",
diff --git a/apps/web/messages/fa/documents.json b/apps/web/messages/fa/documents.json
index 5d228d32..4f95eeca 100644
--- a/apps/web/messages/fa/documents.json
+++ b/apps/web/messages/fa/documents.json
@@ -1,6 +1,7 @@
{
"title": "مستندات",
"newDocument": "صفحه جدید",
+ "uploadMarkdown": "بارگذاری Markdown",
"favoritePages": "موردعلاقه‌ها",
"publicPages": "عمومی",
"privatePages": "خصوصی",
@@ -135,6 +136,8 @@
"exporting": "در حال آماده‌سازی…",
"exportFailed": "خروجی نتوانست همه فایل‌های محافظت‌شده را شامل شود. دوباره تلاش کنید.",
"exportTooLarge": "این صفحه محتوای محافظت‌شده بیش از حد یا بیش از اندازه زیادی برای خروجی یکجا دارد (حداکثر ۵۰ فایل و ۱۰۰ مگابایت).",
+ "markdownTooLarge": "این فایل Markdown برای یک صفحه بیش از حد بزرگ است.",
+ "markdownReadFailed": "خواندن فایل Markdown ممکن نشد.",
"cancel": "لغو",
"linkWorkItem": {
"tab": "تسک‌ها",
diff --git a/apps/web/messages/fr/documents.json b/apps/web/messages/fr/documents.json
index 1f7f566c..33f21c63 100644
--- a/apps/web/messages/fr/documents.json
+++ b/apps/web/messages/fr/documents.json
@@ -1,6 +1,7 @@
{
"title": "Documents",
"newDocument": "Nouvelle page",
+ "uploadMarkdown": "Importer Markdown",
"favoritePages": "Favoris",
"publicPages": "Publiques",
"privatePages": "Privées",
@@ -135,6 +136,8 @@
"exporting": "Préparation…",
"exportFailed": "L'exportation n'a pas pu inclure tous les fichiers protégés. Réessayez.",
"exportTooLarge": "Cette page contient trop de contenu protégé pour être exportée en une fois (maximum 50 fichiers et 100 Mo).",
+ "markdownTooLarge": "Ce fichier Markdown est trop volumineux pour une seule page.",
+ "markdownReadFailed": "Impossible de lire le fichier Markdown.",
"cancel": "Annuler",
"linkWorkItem": {
"tab": "Tâches",
diff --git a/apps/web/messages/id/documents.json b/apps/web/messages/id/documents.json
index bc7feb31..6392b04d 100644
--- a/apps/web/messages/id/documents.json
+++ b/apps/web/messages/id/documents.json
@@ -1,6 +1,7 @@
{
"title": "Dokumen",
"newDocument": "Halaman baru",
+ "uploadMarkdown": "Unggah Markdown",
"favoritePages": "Favorit",
"publicPages": "Publik",
"privatePages": "Pribadi",
@@ -135,6 +136,8 @@
"exporting": "Menyiapkan…",
"exportFailed": "Ekspor tidak dapat menyertakan semua aset yang terproteksi. Coba lagi.",
"exportTooLarge": "Halaman ini memiliki terlalu banyak atau terlalu besar konten terproteksi untuk diekspor sekaligus (maksimum 50 file dan 100 MB).",
+ "markdownTooLarge": "File Markdown ini terlalu besar untuk satu halaman.",
+ "markdownReadFailed": "Gagal membaca file Markdown.",
"cancel": "Batal",
"linkWorkItem": {
"tab": "Item kerja",
diff --git a/apps/web/messages/ko/documents.json b/apps/web/messages/ko/documents.json
index 6c8d2c95..548d0484 100644
--- a/apps/web/messages/ko/documents.json
+++ b/apps/web/messages/ko/documents.json
@@ -1,6 +1,7 @@
{
"title": "문서",
"newDocument": "새 페이지",
+ "uploadMarkdown": "Markdown 업로드",
"favoritePages": "즐겨찾기",
"publicPages": "공개",
"privatePages": "비공개",
@@ -135,6 +136,8 @@
"exporting": "준비 중…",
"exportFailed": "보호된 파일을 모두 포함하여 내보낼 수 없습니다. 다시 시도해 주세요.",
"exportTooLarge": "이 페이지에는 한 번에 내보낼 수 있는 보호된 콘텐츠가 너무 많습니다. 최대 50개 파일, 총 100MB까지 내보낼 수 있습니다.",
+ "markdownTooLarge": "Markdown 파일이 너무 커서 한 페이지에 담을 수 없습니다.",
+ "markdownReadFailed": "Markdown 파일을 읽지 못했습니다.",
"cancel": "취소",
"linkWorkItem": {
"tab": "작업",
diff --git a/apps/web/messages/pt-BR/documents.json b/apps/web/messages/pt-BR/documents.json
index 52abd29a..25c280be 100644
--- a/apps/web/messages/pt-BR/documents.json
+++ b/apps/web/messages/pt-BR/documents.json
@@ -1,6 +1,7 @@
{
"title": "Documentos",
"newDocument": "Nova página",
+ "uploadMarkdown": "Enviar Markdown",
"favoritePages": "Favoritas",
"publicPages": "Públicas",
"privatePages": "Privadas",
@@ -135,6 +136,8 @@
"exporting": "Preparando…",
"exportFailed": "A exportação não pôde incluir todos os arquivos protegidos. Tente novamente.",
"exportTooLarge": "Esta página tem conteúdo protegido demais para exportar de uma vez (máximo de 50 arquivos e 100 MB).",
+ "markdownTooLarge": "Este arquivo Markdown é grande demais para uma única página.",
+ "markdownReadFailed": "Não foi possível ler o arquivo Markdown.",
"cancel": "Cancelar",
"linkWorkItem": {
"tab": "Itens de trabalho",
diff --git a/apps/web/messages/ru/documents.json b/apps/web/messages/ru/documents.json
index 3be455a3..1efe45f7 100644
--- a/apps/web/messages/ru/documents.json
+++ b/apps/web/messages/ru/documents.json
@@ -1,6 +1,7 @@
{
"title": "Документы",
"newDocument": "Новая страница",
+ "uploadMarkdown": "Загрузить Markdown",
"favoritePages": "Избранное",
"newSubpage": "Добавить страницу в {title}",
"addSubpage": "Добавить подстраницу",
@@ -79,6 +80,8 @@
"exporting": "Подготовка…",
"exportFailed": "Не удалось добавить в экспорт все защищённые файлы. Попробуйте ещё раз.",
"exportTooLarge": "На странице слишком много защищённых файлов или они слишком велики для одного экспорта (максимум 50 файлов и 100 МБ).",
+ "markdownTooLarge": "Файл Markdown слишком большой для одной страницы.",
+ "markdownReadFailed": "Не удалось прочитать файл Markdown.",
"cancel": "Отмена",
"publicPages": "Общие",
"privatePages": "Личные",
diff --git a/apps/web/messages/uk/documents.json b/apps/web/messages/uk/documents.json
index 5449b65d..33b6c884 100644
--- a/apps/web/messages/uk/documents.json
+++ b/apps/web/messages/uk/documents.json
@@ -1,6 +1,7 @@
{
"title": "Документи",
"newDocument": "Нова сторінка",
+ "uploadMarkdown": "Завантажити Markdown",
"favoritePages": "Обрані",
"newSubpage": "Додати сторінку до {title}",
"addSubpage": "Додати підсторінку",
@@ -79,6 +80,8 @@
"exporting": "Підготовка…",
"exportFailed": "Не вдалося додати до експорту всі захищені файли. Спробуйте ще раз.",
"exportTooLarge": "На сторінці забагато захищених файлів або вони завеликі для одного експорту (максимум 50 файлів і 100 МБ).",
+ "markdownTooLarge": "Файл Markdown завеликий для однієї сторінки.",
+ "markdownReadFailed": "Не вдалося прочитати файл Markdown.",
"cancel": "Скасувати",
"publicPages": "Спільні",
"privatePages": "Особисті",
diff --git a/apps/web/messages/zh-CN/documents.json b/apps/web/messages/zh-CN/documents.json
index 219525ce..fa1bbecc 100644
--- a/apps/web/messages/zh-CN/documents.json
+++ b/apps/web/messages/zh-CN/documents.json
@@ -1,6 +1,7 @@
{
"title": "文档",
"newDocument": "新建页面",
+ "uploadMarkdown": "上传 Markdown",
"favoritePages": "收藏",
"newSubpage": "在 {title} 下添加页面",
"addSubpage": "添加子页面",
@@ -79,6 +80,8 @@
"exporting": "正在准备…",
"exportFailed": "无法在导出中包含所有受保护的文件。请重试。",
"exportTooLarge": "此页面的受保护文件过多或过大,无法一次导出(最多 50 个文件和 100 MB)。",
+ "markdownTooLarge": "Markdown 文件过大,无法放入一个页面。",
+ "markdownReadFailed": "无法读取 Markdown 文件。",
"cancel": "取消",
"publicPages": "公开",
"privatePages": "私人",
diff --git a/apps/web/src/features/documents/DocumentsPage.tsx b/apps/web/src/features/documents/DocumentsPage.tsx
index c00530e6..b9c8cd7a 100644
--- a/apps/web/src/features/documents/DocumentsPage.tsx
+++ b/apps/web/src/features/documents/DocumentsPage.tsx
@@ -2,6 +2,7 @@
import { useEffect } from 'react';
import { useParams, useRouter } from 'next/navigation';
+import { toast } from 'sonner';
import { useShellRoute } from '@/hooks/useShellRoute';
import { useShell } from '@/context/shellContext';
import { usePermissions } from '@/hooks/usePermissions';
@@ -22,6 +23,7 @@ import DocumentEditor from './components/DocumentEditor';
import DocumentLoadError from './components/DocumentLoadError';
import DocumentLoadingState from './components/DocumentLoadingState';
import DocumentsIndex from './components/DocumentsIndex';
+import { importedMarkdownJson, markdownTitle } from './utils/documentImport';
import { documentBelongsToTab, type DocumentListTab } from './utils/documentList';
import { documentAncestors } from './utils/documentTree';
import { useDebouncedValue } from '@/hooks/useDebouncedValue';
@@ -150,6 +152,33 @@ export default function DocumentsPage() {
}
};
+ const upload = async (file: File) => {
+ let markdown: string;
+ try {
+ markdown = (await file.text()).replace(/^\uFEFF/, '');
+ } catch {
+ toast.error(t('markdownReadFailed'));
+ return;
+ }
+ const contentJson = importedMarkdownJson(markdown);
+ if (!contentJson) {
+ toast.error(t('markdownTooLarge'));
+ return;
+ }
+ try {
+ setSearch('');
+ const newDocument = await createDocument.mutateAsync({
+ title: markdownTitle(file.name),
+ content: markdown,
+ contentJson,
+ isPrivate: listTab === 'private',
+ });
+ router.push(documentPath(projectKey, newDocument.id));
+ } catch {
+ // Mutation errors are reported by the shared query client.
+ }
+ };
+
const remove = async (version: number) => {
if (documentId === null) return;
await deleteDocument.mutateAsync({ documentId, version });
@@ -206,6 +235,7 @@ export default function DocumentsPage() {
onSearchChange={setSearch}
onTabChange={setListTab}
onCreate={(parentId) => void create(parentId, listTab === 'private')}
+ onUpload={(file) => void upload(file)}
onRetry={() => void visibleDocumentsQuery.refetch()}
/>
);
diff --git a/apps/web/src/features/documents/components/DocumentsIndex.tsx b/apps/web/src/features/documents/components/DocumentsIndex.tsx
index 4e4c8150..5e71ed26 100644
--- a/apps/web/src/features/documents/components/DocumentsIndex.tsx
+++ b/apps/web/src/features/documents/components/DocumentsIndex.tsx
@@ -13,6 +13,7 @@ import {
RefreshCw,
Search,
SlidersHorizontal,
+ Upload,
} from 'lucide-react';
import { useTranslations } from 'next-intl';
import type { ProjectDocumentSummary } from '@/lib/api/endpoints/documents';
@@ -66,6 +67,7 @@ export default function DocumentsIndex({
onSearchChange,
onTabChange,
onCreate,
+ onUpload,
onRetry,
}: {
projectKey: string;
@@ -83,6 +85,7 @@ export default function DocumentsIndex({
onSearchChange: (value: string) => void;
onTabChange: (tab: DocumentListTab) => void;
onCreate: (parentId: number | null) => void;
+ onUpload: (file: File) => void;
onRetry: () => void;
}) {
const t = useTranslations('documents');
@@ -102,6 +105,7 @@ export default function DocumentsIndex({
const setCreatedRange = (range: typeof defaults.range) =>
setPreferences((p) => ({ ...p, range }));
const scrollRef = useRef<HTMLDivElement>(null);
+ const uploadInput = useRef<HTMLInputElement>(null);
const restored = useRef(false);
const lastScroll = useRef(preferences.scroll);
useEffect(() => {
@@ -175,16 +179,42 @@ export default function DocumentsIndex({
</div>
</div>
{canCreate && (
- <Button
- type="button"
- size="sm"
- className="h-8 px-2.5 shadow-none"
- disabled={creating}
- onClick={() => onCreate(null)}
- >
- {creating ? <LoaderCircle className="animate-spin" /> : <Plus />}
- <span className="hidden sm:inline">{t('newDocument')}</span>
- </Button>
+ <div className="flex shrink-0 items-center gap-1.5">
+ <input
+ ref={uploadInput}
+ className="sr-only"
+ type="file"
+ accept=".md,.markdown,text/markdown"
+ aria-label={t('uploadMarkdown')}
+ disabled={creating}
+ onChange={(event) => {
+ const file = event.target.files?.[0];
+ event.currentTarget.value = '';
+ if (file) onUpload(file);
+ }}
+ />
+ <Button
+ type="button"
+ variant="outline"
+ size="sm"
+ className="h-8 px-2.5 shadow-none"
+ disabled={creating}
+ onClick={() => uploadInput.current?.click()}
+ >
+ <Upload />
+ <span className="hidden sm:inline">{t('uploadMarkdown')}</span>
+ </Button>
+ <Button
+ type="button"
+ size="sm"
+ className="h-8 px-2.5 shadow-none"
+ disabled={creating}
+ onClick={() => onCreate(null)}
+ >
+ {creating ? <LoaderCircle className="animate-spin" /> : <Plus />}
+ <span className="hidden sm:inline">{t('newDocument')}</span>
+ </Button>
+ </div>
)}
</div>
</header>
diff --git a/apps/web/src/features/documents/hooks/useDocumentCollaboration.ts b/apps/web/src/features/documents/hooks/useDocumentCollaboration.ts
index 519ee732..20120aaa 100644
--- a/apps/web/src/features/documents/hooks/useDocumentCollaboration.ts
+++ b/apps/web/src/features/documents/hooks/useDocumentCollaboration.ts
@@ -1,6 +1,5 @@
import { useCallback, useEffect, useRef, useState } from 'react';
import { useQueryClient } from '@tanstack/react-query';
-import { createDocument } from '@tiptap/core';
import type { Editor } from '@tiptap/react';
import { Step } from '@tiptap/pm/transform';
import { history } from '@tiptap/pm/history';
@@ -20,6 +19,7 @@ import {
readDocumentRecovery,
type DocumentSessionState,
} from '../utils/documentRecovery';
+import { markdownJson } from '../utils/documentImport';
export type DocumentSyncState =
'connecting' | 'saved' | 'saving' | 'offline' | 'error' | 'conflict';
@@ -189,12 +189,7 @@ export function useDocumentCollaboration({
projectKey,
document.id,
current.version,
- current.contentJson ??
- createDocument(
- editor.storage.markdown.parser.parse(current.content),
- editor.schema,
- editor.options.parseOptions,
- ).toJSON(),
+ current.contentJson ?? markdownJson(editor, current.content),
);
if (cancelled || editor.isDestroyed) return;
const recovery = readDocumentRecovery(storageKey);
diff --git a/apps/web/src/features/documents/utils/documentImport.test.ts b/apps/web/src/features/documents/utils/documentImport.test.ts
new file mode 100644
index 00000000..ac1657a3
--- /dev/null
+++ b/apps/web/src/features/documents/utils/documentImport.test.ts
@@ -0,0 +1,54 @@
+import assert from 'node:assert/strict';
+import { after, before, describe, test } from 'node:test';
+import { JSDOM } from 'jsdom';
+import { importedMarkdownJson, markdownTitle } from './documentImport';
+
+describe('importedMarkdownJson', () => {
+ const globals = ['window', 'document', 'navigator', 'Node'] as const;
+ const previous = globals.map((name) => Object.getOwnPropertyDescriptor(globalThis, name));
+ before(() => {
+ const { window } = new JSDOM('<!doctype html>');
+ for (const name of globals) {
+ Object.defineProperty(globalThis, name, { configurable: true, value: window[name] });
+ }
+ });
+ after(() => {
+ globals.forEach((name, index) => {
+ const descriptor = previous[index];
+ if (descriptor) Object.defineProperty(globalThis, name, descriptor);
+ else Reflect.deleteProperty(globalThis, name);
+ });
+ });
+
+ test('parses a file that fits on one page', () => {
+ assert.deepEqual(importedMarkdownJson('# Notes')?.content?.[0]?.type, 'heading');
+ });
+
+ test('rejects a file over the character limit', () => {
+ assert.equal(importedMarkdownJson('a'.repeat(250_001)), null);
+ });
+
+ test('rejects a file whose page has more nodes than the api accepts', () => {
+ const list = Array.from({ length: 4000 }, (_, index) => `- item ${index}`).join('\n');
+ assert.equal(importedMarkdownJson(list), null);
+ });
+});
+
+describe('markdownTitle', () => {
+ test('takes the page title from the file name', () => {
+ assert.equal(markdownTitle('Release notes.md'), 'Release notes');
+ assert.equal(markdownTitle('release-notes.markdown'), 'release-notes');
+ });
+
+ test('matches the extension regardless of case', () => {
+ assert.equal(markdownTitle('Notes.MD'), 'Notes');
+ });
+
+ test('keeps a name that does not end in a markdown extension', () => {
+ assert.equal(markdownTitle('notes.md.bak'), 'notes.md.bak');
+ });
+
+ test('trims surrounding whitespace', () => {
+ assert.equal(markdownTitle(' notes.md '), 'notes');
+ });
+});
diff --git a/apps/web/src/features/documents/utils/documentImport.ts b/apps/web/src/features/documents/utils/documentImport.ts
new file mode 100644
index 00000000..599e54db
--- /dev/null
+++ b/apps/web/src/features/documents/utils/documentImport.ts
@@ -0,0 +1,41 @@
+import { createDocument, Editor, type JSONContent } from '@tiptap/core';
+import { documentEditorExtensions } from '../components/DocumentMarkdownEditor';
+
+// Mirror the api's limits on a page: the content maxLength of the document bodies,
+// and the node and byte caps it checks contentJson against.
+const MAX_MARKDOWN_CHARACTERS = 250_000;
+const MAX_JSON_NODES = 10_000;
+const MAX_JSON_BYTES = 1_000_000;
+
+export const markdownTitle = (filename: string) =>
+ filename
+ .trim()
+ .replace(/\.(md|markdown)$/i, '')
+ .trim();
+
+export const markdownJson = (editor: Editor, markdown: string): JSONContent =>
+ createDocument(
+ editor.storage.markdown.parser.parse(markdown),
+ editor.schema,
+ editor.options.parseOptions,
+ ).toJSON();
+
+const nodeCount = (node: JSONContent): number =>
+ 1 + (node.content ?? []).reduce((sum, child) => sum + nodeCount(child), 0);
+
+// Null when the file is larger than a page the api accepts.
+export function importedMarkdownJson(markdown: string): JSONContent | null {
+ if (markdown.length > MAX_MARKDOWN_CHARACTERS) return null;
+ const editor = new Editor({
+ extensions: documentEditorExtensions({ placeholder: '', codeBlockLabel: '', tableLabel: '' }),
+ });
+ try {
+ const json = markdownJson(editor, markdown);
+ return nodeCount(json) <= MAX_JSON_NODES &&
+ new TextEncoder().encode(JSON.stringify(json)).length <= MAX_JSON_BYTES
+ ? json
+ : null;
+ } finally {
+ editor.destroy();
+ }
+}