Creating & Managing Content

This guide covers how to create and manage books, chapters, and pages in the Docs module, including using the rich text editor, organizing content, and working with version history.

Creating a Book

1. Navigate to Docs from the main navigation.

2. Click the New Book button.

3. Fill in the book form:

1. Click Create.

The book is created and you are redirected to the book workspace where you can start adding chapters and pages.

Personal Books

When you set visibility to "Personal", you are automatically set as the book owner. Only you can see personal books, they do not appear for other team members.

Editing a Book

1. Open the book from the Docs grid.

2. Click the book settings or edit action.

3. Modify the name, description, icon, or visibility.

4. Click Save.

If you change the name, the slug is automatically updated to remain URL-friendly. If the new slug conflicts with an existing book in your tenant, a numeric suffix is appended.

Changing Visibility

When you change a book's visibility:

• Personal to non-personal: The owner is cleared. The book becomes visible to your team (and portal/public if applicable).

• Non-personal to personal: You become the owner. Only you can see the book going forward.

• Internal to portal/public: Portal contacts and/or public visitors gain access to published pages.

• Portal/public to internal: Portal contacts and public visitors lose access.

Deleting a Book

1. Open the book from the Docs grid.

2. Click the Delete action.

3. Confirm the deletion.

Deleting a book soft-deletes it along with all its chapters and pages. This may be recoverable within a retention window depending on your tenant's configuration.

Adding Chapters

Chapters are created inline from the book's sidebar navigation:

1. Open the book workspace.

2. In the sidebar, click the New Chapter button (or the "+" icon).

3. Enter the chapter name (up to 255 characters).

4. Click Create.

The new chapter appears in the sidebar tree. Its sort order is set to the end of the list by default.

Renaming a Chapter

1. In the sidebar, click the chapter name or its edit icon.

2. Enter the new name.

3. Confirm. The slug is updated automatically.

Reordering Chapters

Chapters can be reordered via drag-and-drop in the sidebar:

1. Click and hold the chapter you want to move.

2. Drag it to the desired position in the sidebar.

3. Release. The new order is saved automatically.

Behind the scenes, this sends the full ordered list of chapter IDs to the server, which updates the sort_order on each chapter in one operation.

Deleting a Chapter

1. In the sidebar, click the chapter's delete action.

2. Confirm the deletion.

When a chapter is deleted:

• The chapter is soft-deleted.

• All pages inside the chapter are preserved: they are moved to the book's top level (their chapter_id is set to null).

• Pages are not deleted when their parent chapter is removed.

Creating Pages

From the Book Workspace

1. Open the book workspace.

2. Click the New Page button in the sidebar or toolbar.

3. The page editor opens with the following fields:

1. Write your content using the rich text editor (see below).

2. Click Save.

Creating a Page Inside a Chapter

1. In the sidebar, click the "+" icon next to the chapter name, or use the new page action with the chapter pre-selected.

2. The page editor opens with the chapter field pre-filled.

3. Complete the page and save.

The Tiptap Rich Text Editor

Pages are authored using a Tiptap-based rich text editor that stores content as structured JSON. The editor provides a toolbar with formatting controls and keyboard shortcuts.

Text Formatting

Headings

The editor supports multiple heading levels:

You can also type # , ## , ### , or #### at the beginning of a line followed by a space to create a heading (Markdown shortcut).

Lists

Lists can be nested by pressing Tab to indent or Shift+Tab to outdent.

Code Blocks

For code snippets and technical content:

1. Click the code block button in the toolbar.

2. Or type three backticks (```) at the start of a line and press Enter.

3. Enter your code.

4. Press Ctrl+Enter / Cmd+Enter to exit the code block, or click below it.

Code blocks preserve whitespace and use a monospace font.

Images

To insert an image:

1. Click the image button in the toolbar.

2. Upload an image file or enter an image URL.

3. The image is inserted at the cursor position.

Links

To create a hyperlink:

1. Select the text you want to link.

2. Click the link button in the toolbar (or press Ctrl+K / Cmd+K).

3. Enter the URL.

4. Confirm. The selected text becomes a clickable link.

To remove a link, place your cursor inside the linked text and click the unlink button.

Block Quotes

To create a block quote:

1. Click the quote button in the toolbar.

2. Or type > at the start of a line.

Horizontal Rules

To insert a horizontal divider:

1. Click the horizontal rule button in the toolbar.

2. Or type --- on its own line and press Enter.

Tables

The editor may support table creation depending on the installed Tiptap extensions:

1. Click the table button in the toolbar.

2. Select the number of rows and columns.

3. Fill in the cells.

Content Storage

Content is stored as Tiptap JSON (a structured document format) in a JSONB column. This format preserves all formatting, structure, and embedded media references. When displayed, the JSON is rendered into formatted HTML.

Editing a Page

1. Navigate to the page in the book workspace (click it in the sidebar).

2. Click the Edit button.

3. The page opens in the Tiptap editor with the current content loaded.

4. Make your changes.

5. Click Save.

When you save, the page is updated and a new version snapshot is automatically recorded if the title or content changed.

Changing a Page's Chapter

While editing, you can change which chapter a page belongs to:

1. In the edit form, change the Chapter dropdown.

2. Select a different chapter, or clear it to make the page a top-level page.

3. Save. The page moves to the selected chapter.

Page Status: Draft vs. Published

Every page has a status that controls its visibility:

Draft

• The default status for new pages.

• Visible to your team in the admin interface.

• Hidden from portal contacts and public visitors, even if the book has portal or public visibility.

• The published_at timestamp is null.

Published

• Visible to all audiences that the book's visibility level allows.

• The published_at timestamp is set when the page is first published.

Publishing a Page

1. Open the page in the editor.

2. Change the Status to "Published".

3. Save. The published_at timestamp is set to the current time.

Unpublishing a Page

1. Open the page in the editor.

2. Change the Status to "Draft".

3. Save. The published_at timestamp is cleared. The page is hidden from portal and public views.

Publishing and unpublishing does not create a version snapshot (status changes are tracked via the audit trail).

Page Ordering via Drag-and-Drop

Pages can be reordered within and between chapters:

Reordering Within a Chapter

1. In the sidebar, click and hold the page you want to move.

2. Drag it to the desired position within the same chapter.

3. Release. The new sort order is saved.

Moving Between Chapters

1. Drag a page from one chapter to another.

2. Release it in the desired position within the target chapter.

3. The page's chapter assignment and sort order are both updated.

Moving to Top Level

1. Drag a page out of a chapter and into the top-level area of the sidebar.

2. The page's chapter assignment is cleared and it becomes a top-level page.

The reorder operation sends the complete page order (with chapter assignments) to the server in a single request, ensuring consistency.

Version History

Every edit to a page's title or content automatically creates a version snapshot.

How Versioning Works

• The initial version of a page is version 1, created when the page is first saved.

• Each subsequent save that changes the title or content increments the version number and records a snapshot.

• Snapshots store the title, content, status, and the ID of the user who made the change.

• Status-only changes (publish/unpublish) do not create new version snapshots.

Viewing Version History

1. Open the page in the workspace.

2. Access the version history viewer (available from the page toolbar or detail view).

3. Browse previous versions with their version numbers, content, and author.

Restoring a Previous Version

The version viewer allows you to inspect previous versions and potentially restore them. Restoring a version creates a new version snapshot (it does not overwrite history).

Page Excerpts

Each page can have an optional excerpt, a plain-text summary of up to 2,000 characters. Excerpts serve two purposes:

• Search results: Excerpts appear in search results, giving users a preview of the page content.

• Portal previews: In the portal docs view, excerpts may be displayed alongside page listings.

Excerpts are not auto-generated. You must write them manually in the page editor.

Deleting a Page

1. Navigate to the page in the workspace.

2. Click the Delete action.

3. Confirm the deletion.

Deleted pages are soft-deleted. After deletion, you are redirected to the book workspace.

Entity Links

Books can be linked to CRM entities for cross-referencing:

Adding a Link

1. Open the book workspace.

2. Use the link/association feature in the book detail panel.

3. Search for and select a contact, company, or user.

4. The entity is linked to the book.

Link Types

Removing a Link

1. In the book's linked entities panel, find the entity.

2. Click the remove/unlink action.

3. The link is deleted. The entity itself is not affected.

Full-Text Search Indexing

Page content is automatically indexed for full-text search. The search index is updated whenever a page is created or its title or content changes. Title text receives a higher relevance weight than body content, so searches that match the title will rank higher.

See Search & Navigation for details on using search.