# Fileverse dDocs
[ddocs.new](http://ddocs.new/) is your privacy-focused, open-source alternative to Google Docs. It is an end-to-end encrypted document editor that is optimized for multiplayer collaboration without compromising on speed or people's control over their data.
## 𓆏 Features include:
- End-to-end encryption with post-quantum cryptography
- Real-time and async collaboration
- Suggestion mode (tracked changes) and commenting
- Markdown and LaTeX support
- MermaidJS diagram support
- Import/export of .docx, .md, .pdf, .html and more.
- Dark mode and color themes
- Offline/online editing (continue writing and opening older docs even with no WiFi)
- Cross-device syncing (desktop and mobile)
- Mobile optimized webapp & PWA
- Private access permissions enabled through zero-knowledge proofs
- Private social recovery of account/files, enabled through zero-knowledge proofs
- Version history
- End-to-end encrypted, programmable API optimised for agents (opt-in)
This repository contains:
- `/package` – The core package code.
- Example & demo source code to showcase dDocs functionalities.
## Usage
### Prerequisites
Your app runs Tailwind CSS 3.4 and owns the `@tailwind base/components/utilities` entry. The package ships only editor CSS; preflight, utilities, the `@fileverse/ui` styles, and the KaTeX stylesheet come from your build.
### Install & import
```javascript
import { DdocEditor } from '@fileverse-dev/ddoc';
```
Load stylesheets in this order (Vite emits CSS in import order; in Next put the first two in the root layout and the last two in the editor route):
```javascript
import './globals.css'; // your tailwind entry
import '@fileverse/ui/styles/base'; // tokens and base rules
import 'katex/dist/katex.min.css'; // math; fonts are served as files
import '@fileverse-dev/ddoc/styles'; // editor CSS
```
### Sizing
`DdocEditor` fills its parent: `width: 100%; height: 100%`. The parent must have a definite height. The editor never reads the viewport, so a navbar above it or a footer below it is ordinary layout:
```tsx
```
If the editor renders with no height, its parent has none.
`renderNavbar` output is the editor's first row by default, rendered as is: the editor adds no styling, so return one element with your own background, padding and border. In flow it sits in an unstyled row that only animates the collapse. Without `renderNavbar` nothing is rendered. To place the navbar elsewhere, pass the element to render into. Hold it in state, not in a ref, so the editor re-renders when it attaches:
```tsx
const [navbarEl, setNavbarEl] = useState(null);
```
The layout follows the editor's width, not the window's: in a narrow panel it uses its narrow layout. Known limits: one `DdocEditor` per page; in a narrow editor on a wide screen the comment sheet still covers the whole viewport.
### Peer Dependencies
This package requires the following peer dependencies to be installed in your project:
```bash
npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities @fileverse/ui @fileverse/crypto viem framer-motion frimousse
```
| Package | Version |
| -------------------- | ----------- |
| `@dnd-kit/core` | `>=6.3.1` |
| `@dnd-kit/sortable` | `>=10.0.0` |
| `@dnd-kit/utilities` | `>=3.2.2` |
| `@fileverse/ui` | `^5.4.2` |
| `@fileverse/crypto` | `>=0.0.21` |
| `viem` | `>=2.13.8` |
| `framer-motion` | `>=11.2.10` |
| `frimousse` | `>=0.3.0` |
The peer range is `@fileverse/ui@^5.4.2`. If you ever test a prerelease pairing, pin both packages exactly: a prerelease never satisfies a caret range.
These are externalized from the bundle to avoid duplication when your app already uses them. If you don't have them installed, npm (v7+) will auto-install them for you.
### Update Tailwind Config
```javascript
module.exports = {
presets: [require('@fileverse-dev/ddoc/tailwind')],
content: [
'./src/**/*.{js,ts,jsx,tsx}',
'./node_modules/@fileverse-dev/ddoc/dist/**/*.{js,mjs}',
'./node_modules/@fileverse/ui/dist/**/*.{js,mjs}',
],
};
```
Both dist globs are required, not the single `index.es.js` entry: the dist is chunked (`index.es.js`
statically imports `use-headless-editor-.mjs`), so a single-file entry leaves that chunk's
classes ungenerated.
The preset composes `@fileverse/ui/tailwind` (class-based dark mode, animate plugin, design-system classes) and adds the `mobile: 960px` screen the editor uses.
`tailwindcss@^3.4.0` is an optional peer: the preset runs inside your own Tailwind build, which also supplies the `postcss` and `postcss-js` the ui preset loads. Tailwind 4 is not supported.
### Migrating from 4.x
5.0 stops shipping preflight, Tailwind utilities, the ui stylesheet, the KaTeX stylesheet, and the `html`, `body`, and `*` resets. To upgrade:
1. Add the preset and the two `content` entries above.
2. Import `@fileverse/ui/styles/base` and `katex/dist/katex.min.css` yourself, in the order above.
3. The package no longer ships these global declarations:
- `* { margin: 0; padding: 0 }`
- `html, body { height: 100%; width: 100% }`
- `html, body { overflow: hidden }`
- `body { position: static; user-select: none; -moz-osx-font-smoothing: grayscale }`
- `*, ::before, ::after { border-color: hsl(var(--color-border-default)) }`
If your shell relied on `overflow: hidden` or `user-select: none`, add them to your own
global stylesheet. The rest are covered by Tailwind preflight or the `@fileverse/ui/styles/base`
sheet.
4. Remove any workaround that re-declared `mobile:` classes; the preset generates them.
5. Add `katex` to your own dependencies (`npm install katex@^0.16.11`); the package no longer guarantees it is hoisted.
6. If you styled anything from the old bundle by class name: `.custom-scrollbar` is now `.ddoc-scrollbar`, and `.highlight-comment-bg`, `.is-active`, `.custom-border-bg`, `.animate-fade-in-out`, `.placeholder-disabled`, `.tooltip:before` were removed as unused.
7. The composed `@fileverse/ui` preset defines `rounded-sm` as `calc(var(--radius) - 4px)` (4px)
instead of Tailwind's default 2px, so any surface using ddoc's `rounded-sm` utilities now
renders 4px corners.
8. Third-party CSS ddoc imports (the highlight.js theme, tippy) still ships global `.hljs*` and
`.tippy-box` selectors — this is outside the package's own selector-ownership guarantee.
9. List rules (`ul`, `ol`, and the nested-list counters) are now scoped to
`:where(.ProseMirror, .presentation-mode)` and no longer style `ol`/`ul` outside the editor or
presentation surfaces. If your app relied on ddoc's global list rules elsewhere, own them yourself.
You should now be set to use dDocs!
### Migrating from 6.x
7.0 changes how the editor is sized. No prop was removed.
- Give the editor a parent with a definite height (see Sizing). It no longer sizes itself from `100dvh`.
- Put your footer after the editor in normal flow. `footerHeight` has no effect and can be removed.
- The navbar and toolbars are no longer inside `#editor-canvas`. CSS that used `#editor-canvas` as their ancestor should use `.ddoc-editor-root`.
- The editor no longer wraps your navbar in `