Editing Documents

Learn how to edit documents using ArchDoc's powerful editor.

Accessing a Document

1. Navigate to Dashboard > Documents
2. Click on a document title to open it
3. The document opens in view mode
4. Click the Edit button in the top-right to switch to edit mode

Editor Modes

View Mode

• Read-only view of the document
• See formatted content with all rich text elements rendered
• View sign-off status, linked PRs, and comments
• See document revision history

Edit Mode

When you click Edit, the header switches to show:

• Edit / Preview toggle — switch between the TipTap rich editor and a Markdown preview of the content
• Cancel button — discards unsaved changes and restores the last saved state
• Save button — persists changes to the server

Saving Changes

Local Cache

• Content is automatically cached in localStorage as you type
• Prevents data loss from browser crashes or accidental navigation
• Cache is keyed to the document slug and expires after 24 hours
• The cache is cleared automatically after a successful save

Manual Save

• Click the Save button in the toolbar
• A revision is created and stored in version history

Cancelling Changes

• Click Cancel to discard all unsaved edits
• The editor reverts to the last saved content from the server
• The local cache for this document is also cleared

Document Metadata

Changing the Title

1. Click Edit to enter edit mode
2. Edit the title field at the top of the editor
3. Click Save to persist the new title

Changing the Category

1. In the document view (outside edit mode), find the category dropdown
2. Select:
   • In Progress: Still being drafted
   • Accepted: Approved and final
   • Closed: No longer active
3. The status change is saved immediately without needing to click Save

Document Type

Document type cannot be changed after creation. If needed, create a new document of the correct type and copy the content.

Version History

Every save creates a revision. The Revisions tab in the document view lets you browse and restore previous versions.

Browsing Revisions

1. Open the document and switch to the Revisions tab
2. The left pane lists every revision with its version number, timestamp, and the user who created it (newest first)
3. Click a revision to load its full content into the right-hand preview pane

Previewing a Revision

• The right pane renders the selected revision as Markdown, so you can read it exactly as it was at that point in time
• Revision metadata (author and timestamp) is shown above the preview
• The current document is not modified by previewing — it's safe to click around

Restoring a Revision

1. Open the revision you want to restore in the preview pane
2. Click Restore this version
3. Confirm the action in the dialog

When you restore, ArchDoc:

• Snapshots the document's current state as a new revision first, so the restore itself is reversible
• Overwrites the document with the selected revision's title and content
• Clears the local editor cache so the editor picks up the restored content on next mount

A document_revision_restored entry is written to the activity log for audit purposes.

Linked GitHub Content

Documents can display linked pull requests and commits:

• Linked PRs — shown in the document sidebar with PR number, title, and state
• Linked Commits — shown with the commit SHA and message

These links are created automatically when GitHub integration is configured and documents are synced.

Collaboration

Real-time Editing

When your organization has the collaboration server connected:

• See other users' cursors and avatars in the document header
• Changes from other users sync in real-time
• Collaboration is automatic — just open a document

Seeing Who's Editing

• Avatar circles appear in the document header for each connected user
• Each collaborator is shown with a unique color
• Up to 5 avatars are shown; additional users are shown as a "+N" count

See Collaboration for details.

Comments

Add feedback without editing content:

Adding Comments

1. Select text in the document
2. Click the Comment button
3. Write your comment
4. Submit

Viewing Comments

• Comments appear in the sidebar
• Click to jump to the relevant text
• Reply to create threads

Resolving Comments

• Click Resolve when addressed
• Resolved comments are hidden by default

Permissions

Best Practices

Write Clear Commit Messages

When saving, consider the change you made:

• Did you restructure content?
• Did you add a new section?
• Did you fix errors?

Use Draft Mode

Keep documents as "In Progress" until ready:

• Iterate freely
• Gather feedback
• Polish before accepting

Coordinate with Collaborators

When multiple people edit:

• Communicate who's working on what
• Use comments for discussion
• Review each other's changes

Regular Saves

Even with auto-save:

• Save before leaving
• Save after major changes
• Save before requesting sign-offs

Keyboard Shortcuts

See Editor Features for more shortcuts.

Next Steps

• Learn editor features
• Add diagrams
• Request sign-offs