Reference Manual
A comprehensive guide to every RFRNT feature.
Contents
User management
From Settings → Users, administrators can manage who has access to your RFRNT instance.
User roles
RFRNT has three user roles:
- Admin: Full access to all settings, users, and documents. Can approve or reject any proposed edit. Can manage categories and system settings. Can delete and restore users.
- Editor: Can create and edit documents. Can propose edits to documents they don't own. Can approve edits to documents they own. Can comment on documents and pending edits.
- Viewer: Read-only access to all documents. Cannot create or edit.
Creating users
Click Add User and provide:
- Username: Used for login (must be unique)
- Email: For identification and future notifications
- Display name: Shown on documents and in the activity feed
- Role: Admin, Editor, or Viewer
RFRNT will generate a temporary password and display it once. Share this with the new user securely. They'll be prompted to change it on first login.
Password management
Users can change their own password from Account → Settings. Admins can reset any user's password from the user management screen, which generates a new temporary password that must be changed on login.
Deleting users
Admins can delete users from the user management screen. Deleted users cannot log in, but their contributions remain attributed to them in document history. This is a soft delete—admins can restore deleted users if needed.
Documents
Reference numbers
When you create a document, RFRNT assigns it a permanent reference number automatically. You choose the category (prefix); RFRNT assigns the next available number. This reference never changes, even if you rename the document or move it to a different category.
Reference numbers follow the format PREFIX-NUMBER—for example, DOC-1, SPEC-42, or POL-7. Each category maintains its own counter, so the first document in SPEC is SPEC-1 regardless of how many documents exist in other categories.
Reference numbers are designed to be used outside of RFRNT. Include them in emails, tickets, Slack messages, or other documentation. Anyone with access to your RFRNT instance can find the document instantly by entering its reference number in the search bar.
Shortcodes
For frequently-referenced documents, you can assign a shortcode. Unlike reference numbers, shortcodes are human-readable and memorable. They follow the format PREFIX:NAME, where the name is all caps.
Examples:
DOC:API— Your API documentationPOL:SECURITY— Your security policySPEC:AUTH— Your authentication specification
Shortcodes must be unique across your entire knowledge base. Assign them sparingly to documents that people reference constantly. You can navigate directly to a document by its shortcode using the URL /s/PREFIX:SHORTCODE.
Document ownership
Every document has an owner, set to the creator by default. The owner can:
- Edit the document directly, even when review is required
- Approve or reject proposed changes
- Transfer ownership to another user
- Enable or disable the review requirement
- Delete the document
- Publish the document publicly (if permitted by admin settings)
Admins can do all of the above for any document.
Document types
RFRNT supports two document types, each with its own visual design:
Technical
Sans-serif typography, designed for API docs, specifications, and code-heavy content. Optimized for scanning and reference. Use this for runbooks, technical specifications, and documentation that includes code examples.
Reference
Serif typography, designed for policies, guides, and prose-heavy content. Optimized for sustained reading. Use this for policies, procedures, and narrative documentation.
Choose the type when creating a document. You can change it later from the document settings.
Document statuses
Documents can optionally have a status to track their lifecycle. Statuses are enabled per-category—some categories may not use statuses at all.
Available statuses
| Status | Meaning |
|---|---|
| Draft | Work in progress, not yet ready for review |
| Proposed | Ready for consideration but not yet under formal review |
| Under Review | Currently being evaluated by stakeholders |
| Accepted | Approved and authoritative |
| Rejected | Reviewed and declined |
| Withdrawn | Removed from consideration by the author |
| Implemented | The described work has been completed |
Using statuses
To enable statuses for a category, go to Settings → Prefixes and edit the category. Once enabled, document owners and admins can set and change the status from the document page.
Changing a document's status creates a notification for users watching the document.
Version history
Every edit to a document is saved permanently. RFRNT tracks what changed, who changed it, when, and why.
Viewing history
From any document, click History in the sidebar to see all previous versions. Each entry shows:
- The author of the edit
- The date and time
- The edit summary describing what changed
Click any version to view the document as it appeared at that point in time.
Comparing versions
Select two versions and click Compare to see a side-by-side diff with additions highlighted in green and deletions in red. This makes it easy to understand exactly what changed between any two points in a document's history.
Restoring versions
To restore a previous version, view it and click Restore this version. This creates a new edit that reverts the document to that state—it doesn't delete any history. You can always see what the document looked like before the restore.
Edit summaries
When you save an edit, you must provide a summary describing what you changed and why. Good edit summaries make your version history useful and auditable. Keep them concise but informative: "Fixed typo in section 3" or "Added authentication requirements per security review".
Review workflows
For important documents, you can require that edits be reviewed and approved before they're published.
Enabling review
From a document's settings, enable Require approval for edits. Once enabled, edits from non-owners create a pending edit rather than modifying the document directly.
Proposing changes
When you edit a document that requires approval, your changes are saved as a pending edit. The document owner and all admins can see pending edits and choose to:
- Approve: Merge the proposed changes into the document, creating a new version
- Reject: Discard the proposed changes with an optional comment explaining why
- Comment: Discuss the changes or request modifications before approval
Your queue
From the user menu, select Your Queue to see all pending edits awaiting your review—edits to documents you own or (for admins) any document requiring approval.
Your edits
From the user menu, select Edits to see all pending edits you've submitted, along with their current status (pending, approved, or rejected).
Conflict handling
If the document is edited while a pending edit is outstanding, RFRNT detects the conflict. In some cases, changes can be merged automatically. If manual resolution is required, you'll be prompted to update your proposed changes before they can be approved.
Notifications
RFRNT notifies you of activity relevant to your work. You receive notifications when documents you own or watch are edited, commented on, or have their status changed. You're also notified about pending edits you've submitted—when they're approved, rejected, or commented on.
Click the bell icon in the header to see recent notifications. Clicking a notification marks it as read and navigates to the relevant document or pending edit. Use Mark All Read to clear all unread notifications, or See All to view your full notification history.
Watching documents
Watch documents to receive notifications when they're edited, commented on, or have their status changed.
Watching a document
From any document, click Watch in the sidebar to start watching it. Click again to stop watching.
You don't need to watch documents you own—you automatically receive notifications for activity on documents you own.
Managing your watches
From the user menu, select Watching to see all documents you're currently watching. From this page, you can stop watching any document.
Pinned documents
Admins can pin important documents so they appear at the top of the document list for easy access.
Pinning to the main page
From a document, click Pin in the sidebar to pin it to the main documents page. Pinned documents appear before unpinned documents in the list.
Pinning to a category
Documents can also be pinned to specific category pages. When viewing documents filtered by category, pinned documents appear at the top of that category's list.
Reordering pinned documents
When multiple documents are pinned, admins can reorder them using the position controls. The order is preserved.
Categories
Categories (also called prefixes) organize your documents and determine their reference number format. Manage categories from Settings → Prefixes.
Creating categories
Each category has:
- Code: The prefix used in reference numbers (e.g.,
DOC,SPEC). Must be unique and uppercase. - Name: A human-readable name for the category
- Description: Optional explanation of what this category is for
Category settings
Each category can have additional settings:
- Comments enabled: Whether documents in this category can have comments
- Statuses enabled: Whether documents in this category can have status labels
- Upkeep interval: Days between expected updates (for upkeep tracking)
Access control
Categories can be restricted to specific users. By default, all users with Editor or higher role can create documents in any category. To restrict a category:
- Edit the category in Settings → Prefixes
- Enable access restrictions
- Add specific users who should have access
Viewers can always read documents in restricted categories, but only users on the access list can create or edit documents in that category.
Publishing
Documents can be published publicly, making them accessible without logging in.
Publishing a document
From a document you own (or any document if you're an admin), click Publish in the sidebar. The document is now accessible at its public URL.
Public URLs
Published documents are accessible at /p/PREFIX-NUMBER. For example, if you publish DOC-1, it's accessible at /p/DOC-1. This URL can be shared with anyone—no login required.
Unpublishing
To make a published document private again, click Unpublish in the sidebar. The public URL will no longer work.
Owner publish permission
By default, only admins can publish documents. Admins can enable owner publishing from Settings → General, which allows document owners to publish their own documents.
Images
RFRNT supports uploading and embedding images in documents.
Uploading images
While editing a document, drag and drop an image into the editor. RFRNT uploads it and inserts the Markdown image syntax automatically.
Alternatively, use the standard Markdown image syntax: 
Content-addressed storage
Images are stored using content-addressed storage. Each image is identified by its SHA-256 hash, which means:
- Duplicate images are automatically deduplicated
- Image URLs never change
- Images are served from
/objects/HASH
Supported formats
RFRNT accepts common image formats including PNG, JPEG, GIF, and WebP.
Search
RFRNT provides fast, full-text search across all documents.
Basic search
Type any text in the search bar to find documents containing those words. Results are ranked by relevance, with matches in titles weighted higher than matches in body text.
Reference lookup
Enter a reference number (like DOC-123) or shortcode (like DOC:API) to jump directly to that document. This is the fastest way to navigate when you know the document's identifier.
Live search
Search results appear as you type, showing matching documents instantly. Press Enter or click a result to navigate.
Search filters
From the full search page, narrow your search with filters:
- Category: Filter by document category (prefix)
- Type: Filter by document type (technical or reference)
- Author: Filter by document creator
Backlinks
RFRNT automatically tracks which documents link to which. At the bottom of every document, you'll see a list of all documents that reference the current one.
How backlinks work
When a document mentions another document's reference number (like DOC-123) or shortcode (like DOC:API), RFRNT records this link. The referenced document shows all documents that link to it.
Using backlinks
Backlinks help you understand the context and importance of a document:
- A document with many backlinks is probably important; changes to it may have wide-reaching effects
- A document with no backlinks might be orphaned or outdated
- Backlinks reveal relationships between documents that might not be obvious
Backlinks update in real-time as documents are edited.
Upkeep
RFRNT can remind you when documents need attention—helping you keep your knowledge base current.
Upkeep intervals
Each category can have an upkeep interval: the number of days between expected updates or reviews. Set this in Settings → Prefixes when editing a category.
Viewing upkeep status
From the user menu, select Upkeep to see documents that may need attention. This page shows documents that haven't been edited or reviewed within their category's upkeep interval.
View tracking
RFRNT tracks view counts for each document. This helps identify which documents are actively used and which might be candidates for archiving or updating. View counts are visible on the document page.
Markdown
All documents are written in GitHub Flavored Markdown. RFRNT supports the full GFM specification plus some extensions.
Standard features
All standard Markdown features are supported:
- Headings, paragraphs, and line breaks
- Bold, italic, and strikethrough text
- Ordered and unordered lists
- Links and images
- Blockquotes
- Horizontal rules
GitHub Flavored Markdown
GFM extensions are also supported:
- Tables with column alignment
- Fenced code blocks with language specification
- Task lists with checkboxes
- Autolinks for URLs
Syntax highlighting
Fenced code blocks with a language specified are syntax-highlighted. For example:
```python
def hello():
print("Hello, world!")
```Common languages are supported including Python, JavaScript, TypeScript, Rust, Go, Ruby, Java, C, C++, Shell/Bash, SQL, JSON, YAML, HTML, CSS, and many more.
Document links
Reference other documents by simply including their reference number or shortcode in your text:
DOC-123links to document DOC-123DOC:APIlinks to the document with shortcode API in category DOC
These are automatically converted to clickable links when the document is rendered.
Sidenotes
Use footnote syntax for sidenotes that appear in the margin on wide screens:
All API requests require authentication[^1].
On narrow screens, sidenotes appear as traditional footnotes at the bottom of the document.
Comments
RFRNT supports two types of comments for discussion and feedback.
Document comments
Comments can be enabled per-category. When enabled, users can leave comments on documents for general discussion, questions, or feedback. Document comments appear at the bottom of the document and are visible to all users with access to the document.
To enable comments for a category, go to Settings → Prefixes and edit the category.
Pending edit comments
Pending edits have their own comment thread, separate from document comments. Use pending edit comments to discuss proposed changes during review—ask questions, request modifications, or explain your reasoning.
Pending edit comments are visible to the author of the pending edit, the document owner, and all admins.
Rate limiting
To prevent abuse, comments are rate-limited.