An Emacs client for Org Social, a decentralized social network that works with Org Mode files over HTTP.
Important note!: The Relay server is required for org-social.el to work. You can think of it as the client's backend, or software that synchronizes data. You can use:
- Official instance
- unofficial instances
- A Relay instance on your local machine.
It is your decision.
Option 1: Local file + Your own hosting
- Create your social.org file
- Upload it to a web server so others can access it
- Configure org-social.el with the required settings:
(setq org-social-file "~/social.org") ;; Path to your local file
(setq org-social-relay "https://relay.org-social.org/") ;; Relay server
(setq org-social-my-public-url "https://example.com/social.org") ;; Your public URLOption 2: Using Org Social Host (simplified hosting)
If you don't have your own web server, you can use Org Social Host for automatic hosting:
- Sign up at the public host to get your
vfile URLandpublic URL - Configure org-social.el with:
(setq org-social-file "http://host.org-social.org/vfile?token=YOUR_TOKEN&ts=TIMESTAMP&sig=SIGNATURE")
(setq org-social-relay "https://relay.org-social.org/")
(setq org-social-my-public-url "http://host.org-social.org/your-nick/social.org")- View timeline:
M-x org-social-timeline - Create new post:
M-x org-social-new-post - Reply to posts in timeline: Press
ron a post - Interact with the entire community through the relay server
M-x package-install RET org-social RET
Add the following to your Emacs config:
(use-package request)
(use-package org-social
:vc ( :url "https://github.com/tanrax/org-social.el"
:rev :newest))You can install the development version from the develop branch.
Add the following to your Emacs config:
(use-package request)
(use-package org-social
:vc ( :url "https://github.com/tanrax/org-social.el"
:rev "develop"))To use the old version 1, you need to use the v1 branch:
(use-package request)
(use-package org-social
:vc ( :url "https://github.com/tanrax/org-social.el"
:rev "v1"))M-x package-reinstall RET org-social RET restart-emacs RET
Option 1: Local File
;; Required: Set the path to your social feed file
(setq org-social-file "~/my-social-feed.org")
;; Required: Configure Org Social Relay server
;; See public relay list: https://github.com/tanrax/org-social/blob/main/org-social-relay-list.txt
(setq org-social-relay "https://relay.org-social.org/")
;; Required: Set your public social.org URL (where others can access your feed)
(setq org-social-my-public-url "https://example.com/social.org")Option 2: Using vfile (Org Social Host)
If you're using Org Social Host, you can use a vfile URL instead of a local file path. The client will automatically download and sync your file with the host.
;; Use your vfile URL from the host signup
(setq org-social-file "http://host.org-social.org/vfile?token=YOUR_TOKEN&ts=TIMESTAMP&sig=SIGNATURE")
;; Required: Configure Org Social Relay server
(setq org-social-relay "https://relay.org-social.org/")
;; Required: Set your public URL (from host signup)
(setq org-social-my-public-url "http://host.org-social.org/your-nick/social.org")When using a vfile:
- The file is automatically downloaded from the host when you open it
- Your local copy is cached as
~/.emacs.d/v-social.org(single-account) or~/.emacs.d/v-social-ACCOUNT.org(multi-account) - Every time you save (
C-x C-s), changes are automatically uploaded to the host - Uses native Emacs url-retrieve functions (no external dependencies required)
org-social.el supports multiple accounts, allowing you to manage different social feeds (e.g., personal, blog, work) from a single Emacs session.
Using local files:
(require 'org-social-accounts)
(org-social-add-account "personal"
:file "~/social-personal.org"
:relay "https://relay.org-social.org/"
:public-url "https://example.com/personal.org"
:after-save-file-hook nil
:after-fetch-posts-hook nil)
(org-social-add-account "blog"
:file "~/social-blog.org"
:relay "https://relay.org-social.org/"
:public-url "https://blog.example.com/blog.org"
:after-save-file-hook (lambda ()
(message "Blog social file saved!"))
:after-fetch-posts-hook (lambda ()
(message "Blog posts fetched!")))
;; Set the default account to use
(org-social-switch-account "personal")
;; Switch accounts at any time with M-x org-social-switch-accountUsing vfiles (Org Social Host):
You can also use vfile URLs for multi-account setups. Each account will have its own cache file:
(require 'org-social-accounts)
(org-social-add-account "personal"
:file "http://host.org-social.org/vfile?token=TOKEN1&ts=TS1&sig=SIG1"
:relay "https://relay.org-social.org/"
:public-url "http://host.org-social.org/mynick/social.org")
(org-social-add-account "blog"
:file "http://host.org-social.org/vfile?token=TOKEN2&ts=TS2&sig=SIG2"
:relay "https://relay.org-social.org/"
:public-url "http://host.org-social.org/myblog/social.org")
;; Set the default account to use
(org-social-switch-account "personal")When using vfiles with multi-account:
- Each account's vfile is cached separately:
~/.emacs.d/v-social-personal.org,~/.emacs.d/v-social-blog.org - Switching accounts automatically loads the correct cached file
- Saving uploads to the correct host account
;; Hide Reply, Vote, and Profile buttons for a cleaner timeline view. Change to 't' to hide them. Keyboard shortcuts 'r', 'v', and 'P' still work
(setq org-social-hide-post-buttons nil)
;; Set base URL for live post previews. When configured, a Share button will appear in post buttons
;; that opens the post preview in the system browser with URL-encoded post URL
;; Example: (setq org-social-live-preview-url "https://preview.org-social.org/?post=")
(setq org-social-live-preview-url "https://preview.org-social.org/?post=")
;; Use only relay followers instead of local follow list
(setq org-social-only-relay-followers-p nil)
;; Set default language for new posts and polls (optional)
;; When set, the :LANG: property will be automatically filled with this value
;; Examples: "en" for English, "es" for Spanish, "fr" for French
;; Leave as nil to keep :LANG: field empty (default behavior)
(setq org-social-default-lang nil) ; or "en", "es", "fr", etc.
;; Maximum age of posts to fetch from feeds (in days)
;; Set to nil to download all posts without filtering (default: 14 days)
(setq org-social-max-post-age-days 14) ; or 7, 30, nil, etc.
;; Maximum number of concurrent feed downloads
;; Limits parallel downloads to avoid overwhelming system resources
;; Recommended range: 10-30 (default: 20)
(setq org-social-max-concurrent-downloads 20) ; or 10, 30, etc.
;; Filter timeline posts by language
;; Only show posts in specified languages (using :LANG: property)
;; Set to nil to show all posts regardless of language (default)
;; Examples: '("en") for English only, '("en" "es") for English and Spanish
(setq org-social-language-filter nil) ; or '("en" "es"), '("en"), etc.
;; Optionally, configure global keybindings
(keymap-global-set "C-c s t" #'org-social-timeline)
(keymap-global-set "C-c s n" #'org-social-new-post)
(keymap-global-set "C-c s o" #'org-social-open-file)
(keymap-global-set "C-c s p" #'org-social-new-poll)
(keymap-global-set "C-c s m" #'org-social-mention-user)The optimized partial download feature (org-social-max-post-age-days) works best with traditional web servers. Some hosting platforms have limitations:
Cloudflare CDN
- Does not provide
Content-LengthorContent-Rangeheaders - Fallback: Automatically downloads full feed and filters client-side
- Impact: No bandwidth savings, but still works correctly
Codeberg.org
- Implements aggressive rate limiting (HTTP 429) when multiple feeds are downloaded simultaneously
- Fallback: Automatically downloads full feed without filtering when rate limit is detected
- Impact: May download older posts than configured
org-social-max-post-age-days
GitHub Raw Content
- Provides proper HTTP Range support
- Works optimally with partial downloads
For best performance with partial downloads, host your social.org file on a traditional web server (Apache, Nginx, etc.) or GitHub/GitLab raw content URLs. The client handles all cases gracefully with automatic fallbacks.
| Variable | Description | Default | Required | Type |
|---|---|---|---|---|
org-social-file |
Path to your Org-social feed file | "~/social.org" |
✅ | file |
org-social-relay |
URL of the Org Social Relay server for registering your feed and discovering mentions, replies, and social interactions. | "https://relay.org-social.org" |
✅ | string |
org-social-my-public-url |
Public URL of your social.org file where others can access your feed. | nil |
✅ | string |
org-social-hide-post-buttons |
Hide Reply, Vote, and Profile buttons from timeline posts for a cleaner view. Keyboard shortcuts still work. | nil |
❌ | boolean |
org-social-live-preview-url |
Base URL for live post previews. When set, a Share button appears in post buttons that opens the post preview in the system browser with URL-encoded post URL. Set to nil to hide the Share button. |
"https://preview.org-social.org/?post=" |
❌ | string |
org-social-only-relay-followers-p |
When non-nil, use only feeds from the relay server. Requires relay configuration. | nil |
❌ | boolean |
org-social-default-lang |
Default language code for new posts and polls. When set, automatically fills the :LANG: property with a two-letter ISO 639-1 language code (e.g., "en", "es", "fr"). When nil or empty string, the :LANG: field remains empty. |
nil |
❌ | string |
org-social-max-post-age-days |
Maximum age of posts to fetch from feeds, in days. Uses optimized partial downloads with HTTP Range requests (saves up to 89% bandwidth). Each feed is downloaded in a separate thread for parallel execution without blocking Emacs. For servers supporting Range requests (87.5%), only recent posts are downloaded. For others, the full feed is downloaded and filtered. Set to nil to disable filtering and download all posts. |
14 |
❌ | integer or nil |
org-social-max-concurrent-downloads |
Maximum number of concurrent feed downloads. When loading the timeline, feeds are downloaded in parallel. This setting limits simultaneous downloads to avoid overwhelming system resources or triggering rate limits on remote servers. Recommended range: 10-30. Higher values = faster but more resource intensive. | 20 |
❌ | integer |
org-social-language-filter |
List of language codes to filter timeline posts. Only posts with :LANG: property matching these codes will be shown. When nil, all posts are shown regardless of language. Posts without a :LANG: property or with empty :LANG: are hidden when filter is active. Uses ISO 639-1 two-letter language codes. |
nil |
❌ | list of string or nil |
You can customize these variables through Emacs' customization interface:
M-x customize-group RET org-social RETRegister a new Org Social account with a name and properties.
Required properties:
:file- Path to the social.org file for this account
Optional properties:
:relay- Relay server URL:public-url- Public URL where your feed is accessible:after-save-file-hook- Function to run after saving the file:after-fetch-posts-hook- Function to run after fetching posts
Switch to a different Org Social account. You can call this interactively with M-x org-social-switch-account and select from your configured accounts.
Return a list of all registered account names.
Remove an account from the registry. If you remove the currently active account, org-social.el will switch to backward-compatible mode using global variables.
Downloads feeds from people you follow and displays a unified timeline with enhanced navigation and reply functionality. The timeline follows the Org Social specification including:
- Proper
* Postssection with post metadata :PROPERTIES:drawers with metadata (ID, LANG, TAGS, CLIENT, MOOD, etc.)- Author information as comments
- Original content preservation with multiline support
Make a new post in your social feed.
Create a new poll in your Org-social feed.
Create a migration post to notify followers that your feed has moved to a new URL. This function prompts for:
- Old URL: The previous location of your social.org file
- New URL: The new location where your social.org file is hosted
Automatic Migration Processing:
org-social.el automatically detects and processes migrations in two scenarios:
- Local migrations - When you open your social.org file or view the timeline, the latest migration post in YOUR file is detected and applied
- Remote migrations - When downloading feeds from followers, if someone has migrated their URL, org-social.el automatically updates all references in your social.org file
This includes updating:
#+FOLLOW:entries:REPLY_TO:properties:INCLUDE:properties (boosts)- Mention links
[[org-social:...]]
Important notes:
- Only the most recent migration (based on timestamp) from each feed is processed
- Remote migrations are only applied if the feed's URL matches the old URL in the migration post
- Your social.org file is automatically saved after applying remote migrations
- You'll see a message indicating how many updates were made
Example migration post:
**
:PROPERTIES:
:ID: 2025-11-23T12:15:04+0100
:CLIENT: org-social.el
:MIGRATION: https://old-site.com/social.org https://new-site.com/social.org
:END:
Insert a mention of a user in your post.
Check and display mentions from the relay server in a separate buffer. Only works when relay is configured.
Browse and follow users from the relay server. Opens a buffer showing all users registered in the relay with their avatars, descriptions, and follow/unfollow buttons. Allows you to:
- View all users from the relay with their profile information
- Follow new users with the "+ Follow" button
- Unfollow existing users with the "− Unfollow" button
- View user profiles with the "👤 Profile" button
- Automatically updates your social.org file when you follow/unfollow users
Verifies that your file has the correct structure.
Open the Org-social feed file and enable org-social-mode.
Set up Org-social for first-time use.
Creates a reply to a post in the timeline (available when viewing the timeline).
View the profile of the post author at current position (available when viewing the timeline).
Save the current Org-social file and run associated hooks.
| Keybinding | Function | Description |
|---|---|---|
c |
New post | Create a new post |
l |
New poll | Create a new poll |
r |
Reply | Reply to the post at point |
R |
React | Add a reaction to the post at point |
n |
Next post | Navigate to the next post |
p |
Previous post | Navigate to the previous post |
t |
View thread | View thread for current post |
P |
View profile | View the profile of the post author |
N |
Notices | View notices and mentions |
G |
Groups | View groups |
D |
Discover | Browse and follow users from the relay |
T |
Timeline | Go back to timeline |
g |
Refresh | Refresh the current view |
b |
Kill buffer | Close the current buffer |
q |
Quit | Quit Org Social UI |
When your cursor is positioned in the content area of a post, you can use Org mode commands:
| Keybinding | Function | Description |
|---|---|---|
C-c C-c |
org-ctrl-c-ctrl-c | Context-aware Org command (recalculate tables, execute code) |
C-c * |
org-table-recalculate | Force recalculation of table formulas |
C-c C-v C-e |
org-babel-execute-src-block | Execute source code block |
Posts in org-social.el support interactive Org mode features, allowing tables with formulas, executable code blocks, and other dynamic content to work directly in the timeline and thread views.
Create posts with Org mode tables and formulas that can be recalculated:
**
:PROPERTIES:
:ID: 2025-01-15T10:00:00+0100
:END:
Monthly budget:
| Category | Amount | Percentage |
|-----------+--------+------------|
| Rent | 1200 | 48.00 |
| Food | 400 | 16.00 |
| Transport | 200 | 8.00 |
| Savings | 400 | 16.00 |
|-----------+--------+------------|
| Total | 2200 | 100.00 |
#+TBLFM: @2$3=100*$2/@6$2;%.2f::@3$3=100*$2/@6$2;%.2f::@4$3=100*$2/@6$2;%.2f::@5$3=100*$2/@6$2;%.2f::@6$2=vsum(@2..@5)::@6$3=vsum(@2..@5)
How to use: Position your cursor on any table cell and press C-c C-c to recalculate all formulas.
Share code that others can execute directly in the timeline:
**
:PROPERTIES:
:ID: 2025-01-15T11:00:00+0100
:END:
Quick Fibonacci calculator:
#+BEGIN_SRC python :results output
def fibonacci(n):
if n <= 1:
return n
return fibonacci(n-1) + fibonacci(n-2)
for i in range(10):
print(f"F({i}) = {fibonacci(i)}")
#+END_SRC
How to use: Position your cursor inside the code block and press C-c C-c to execute it.
All standard Org mode formatting works in posts:
- Bold:
**text** - Italic:
/text/ Code:=text=or~text~- Links:
[[url][description]] - Lists, checkboxes, and more
- TAB-based folding is not fully implemented yet
- Some advanced Org features may not work perfectly in the widget context
You can use the following hooks to perform additional actions automatically:
| Name | Description |
|---|---|
org-social-after-save-file-hook |
Runs after saving the social file. Useful for automating tasks like uploading to a remote server or syncing with other services. |
org-social-after-fetch-posts-hook |
Runs after all feeds have been fetched and processed. |
For traditional single-account configuration, you can add hooks globally:
(add-hook 'org-social-after-save-file-hook
(lambda ()
(call-process-shell-command
(format "scp %s %s"
org-social-file
"user@server:/your/path/social.org")
nil 0)))When using multi-account configuration, you can specify hooks for each account individually:
(org-social-add-account "personal"
:file "~/social-personal.org"
:relay "https://relay.org-social.org/"
:public-url "https://example.com/personal.org"
:after-save-file-hook (lambda ()
(message "Personal social file saved!")
;; Upload to server
(call-process-shell-command
"scp ~/social-personal.org user@server:/path/personal.org"
nil 0)))
(org-social-add-account "blog"
:file "~/social-blog.org"
:relay "https://relay.org-social.org/"
:public-url "https://blog.example.com/blog.org"
:after-fetch-posts-hook (lambda ()
(message "Blog posts fetched!")
;; Custom notification
(notifications-notify
:title "Org Social"
:body "New blog posts available")))- Setup: Configure
org-social-fileand create your social.org file - View timeline: Use
M-x org-social-timelineorC-c s t - Navigate: Use
n/pto move between posts in the timeline - Reply: Press
rwhen positioned on a post to create a reply - Vote on polls: Press
vwhen positioned on a poll to vote - Create posts: Use
M-x org-social-new-postorC-c s n - Create polls: Use
M-x org-social-new-pollorC-c s p - Save and sync: Use
C-x C-sto save with hooks
GPL-3.0 - See LICENSE file for details.
See CHANGELOG.md for detailed release notes.
Feel free to fork the repository and submit pull requests to the develop branch.
