📄 Room Documents

A complete guide to creating collaborative, media-rich documents inside Study Rooms — perfect for lesson plans, research notes, team wikis, and curated knowledge bases.

💡

What are Room Documents?

A Room Document is a rich, editable document that lives inside a Study Room. Unlike regular posts or chat messages, room documents support full formatting, images, embedded YouTube videos, audio players, PDF references, and linked entities — all in one scrollable page.

They are designed for classroom lesson plans, research summaries, team onboarding guides, curated reading lists with embedded media, or any long-form collaborative content that needs more than plain text.

✏️

Rich editing

Full TipTap editor with headings, lists, bold/italic, code blocks, undo/redo, and more.

🖼️

Embedded media

Insert images, YouTube videos, audio files, PDFs, and links directly from the room's bookshelf.

👥

Collaborative

Multiple members can edit the same document — changes are tracked with an edit history.

🔗

Entity relations

Link documents to characters, places, events, and other room entities for AI-powered context.

🔐

Who can create and edit documents?

Room documents have clear permission rules to keep content organized:

👑 Owner

Can create, edit, and delete any document in the room.

🛠️ Moderator

Can create and edit any document.

📤 Contributor

Can create documents and edit only their own documents.

👤 Member

Can read documents but cannot create or edit them.

Tip:Want to let all members contribute? Change their role to Contributor in the room's Members tab. Role changes take effect immediately.

📝

Creating a Room Document

You can create a document from the room's Bookshelf tab. Here is the step-by-step process:

Navigate to the room's Bookshelf add page

Go to your Study Room and click the Bookshelf tab, then click Add to Bookshelf. On the add page, look for the 📄 New Document card and click it.

Choose your starting point

You have two options on the Source screen:

📤 Upload a file — upload a PDF, Word document, or text file. We will extract the text so you can edit it. Drag-and-drop is supported.
✏️ Start blank — begin with an empty editor and write from scratch.

Give your document a title and description

A clear, descriptive title helps room members find the document on the bookshelf. The description (optional) provides a brief summary of what the document contains.

Write and format your content

Use the rich text editor to write your content. The toolbar gives you full control over headings, lists, bold and italic text, quotes, code blocks, and more. You can paste content directly from Word, Google Docs, or Markdown — it will be cleaned and formatted automatically.

Click Create Document

Once you are happy with the content, click the 📄 Create Documentbutton. Your document will appear on the room's bookshelf immediately (pending approval if the room requires it).

File upload notes: Supported formats are PDF, DOCX, DOC, TXT, Markdown, CSV, and HTML — up to 25 MB. The original file is retained on Cloudinary for provenance, and the extracted text is placed in the editor for you to review and polish.

✏️

Editing a Room Document

Once a document exists, permitted users can edit it at any time. Here is how:

Open the document from the bookshelf

On the room's Bookshelf tab, find your document in the " Room Documents" section. Click its title to open the detail view.

Click the Edit button

On the document detail page, click the ✏️ Edit button in the header. This opens the full edit page with the current content loaded in the editor.

Make your changes

Edit the title, description, or body content. The editor has the same full toolbar as when creating — including the ability to insert media (see next section).

Save your changes

Click 💾 Save Changes. Your edit is recorded in the document's edit history, visible at the bottom of the edit page. Each entry shows who edited, what action was taken, and when.

Edit history:Every save creates a log entry with the editor's name, timestamp, and action type. This gives you a full audit trail — useful for classrooms where multiple contributors may be polishing the same document.

🎬

Inserting media into a document

Room documents can embed images, YouTube videos, audio files, links, and PDF references — all pulled directly from the room's bookshelf. This makes documents ideal for lesson plans that combine text with supporting media.

🖼️ Images & Photos

Click the Image button in the editor toolbar (or right-click → Insert Image). Browse the room's gallery, your personal media library, or upload a new image. Images are resizable — click an image in the editor and use the resize controls in the toolbar, or right-click for size options.

📺 YouTube Videos

Click the Video button (or right-click → Browse Bookshelf), switch to the Bookshelf tab, and filter by 📺 Video. Select a YouTube video from the room's bookshelf — it will embed as a playable, responsive 16:9 player right inside the document.

🎵 Audio Files

Click the Audiobutton to insert an audio player. Choose from the room bookshelf's Audio filter or upload a new file. Great for embedding podcasts, recorded lectures, or language lessons.

📄 PDFs & Documents

Click Browse Bookshelf (right-click menu) and filter by 📕 PDF to see all PDFs in the room. Selecting a PDF inserts a styled document card showing the title, file type badge, file size, and an Open in new tab link. This is perfect for syllabi, reading assignments, or reference materials.

🔗 Links

External links from the room's bookshelf can be inserted as styled link cards with title and description. Filter by🔗 Links in the Bookshelf tab.

Quick access: Right-click anywhere in the editor to open the context menu, then choose 📚 Browse Bookshelf to see all room media in one place — filtered by type. This is the fastest way to embed bookshelf items without leaving the editor.

🔗

Linking documents to entities

Every room document has an Entity Relationspanel on its edit page. This lets you link the document to characters, places, events, objects, and other items in the room's knowledge graph.

Why link entities?

When you link a document to a character (e.g., “about Abraham Lincoln”) or a place (e.g., “set in Gettysburg”), Sage AI can use those connections to answer questions like “What documents do we have about the Civil War?” or “Show me everything related to this character.” It builds a richer, more queriable knowledge base.

How to add a relation

1. On the document edit page, scroll down to the Entity Relations panel.

2. Click 🔗 Link to open the search panel.

3. Search for an entity by name — characters, places, timeline events, objects, even other documents.

4. Choose a relation type from the suggested list (e.g., “about”, “references”, “documents”).

5. Click Create Relation. The link appears immediately and is visible to all room members.

Smart suggestions:The relation type suggestions adapt based on what you are linking. Linking a document to a character suggests “about”, “features”, and “cites”. Linking to a place suggests “set in” and “references”. Choose from the list or type your own custom relation.

📖

Reading and sharing documents

Room documents appear on the room's bookshelf alongside books, serials, and uploaded files. Click any document to open its detail page, which shows the full formatted content.

📖

Full-page reader

Click Full Page on the detail page to open a distraction-free reading view with the document rendered in its entirety — including all embedded media.

💬

Discussion thread

Every document has its own discussion channel where members can leave comments, ask questions, and share insights.

🔗

Entity links

Linked entities appear as badges — click any to jump to that entity's detail page in the room's world.

📎

Source file

If the document was created from an uploaded file, the source file is linked on the detail page for reference and download.

💡

Tips & best practices

Use for lesson plans: Add your lesson content, embed a YouTube lecture, attach a PDF reading assignment, link it to the relevant historical figure — and you have a complete, self-contained lesson in one page.

Build the bookshelf first: Upload your media (images, PDFs, YouTube links) to the room bookshelf before creating your document. Then you can insert everything from the Bookshelf tab without leaving the editor.

Keep documents focused: Each document should cover one topic, lesson, or research question. You can always link documents together with entity relations for broader context.

Remember to save: The editor does not auto-save. Click 💾 Save Changes regularly while editing, especially after inserting media.

🚀

Ready to try it?

📚

Go to your Study Room

Open a room, navigate to the Bookshelf, and create your first document.

→🏛️

Back to Study Rooms Tutorial

Learn more about Study Rooms — chat, Sage AI, calendar, and room connections.

→📘

All Tutorials

Browse the full tutorial library for more guides.

→

Create your first Room Document

Open a Study Room, go to the Bookshelf, and start building collaborative, media-rich documents.

📄 Get Started →