Site icon Efficient Coder

Org-social: The Plain-Text Decentralized Social Network Revolution

高效码农

A 3,000-Word Plain-Text Social Network: The Complete Org-social Handbook

“What if your entire social-media life was nothing more than a single text file on the web?”

Meet Org-social, a decentralized social platform that lives inside an Org Mode file served over HTTP—no sign-ups, no databases, no lock-in.
Below you’ll find a single, long-form guide that walks you through everything the official README covers, rewritten for an English-speaking, junior-college audience and optimized for both human readers and search engines.

1. What Exactly Is Org-social?

Org-social is a decentralized social network that stores every post, reply, poll, and profile detail in one human-readable Org Mode file. You host the file anywhere that can serve plain text (GitHub Pages, your own VPS, Gitea, Netlify, etc.). Anyone with the link can read or follow you.

Core Values (copied from the original)

Value Meaning
Simplicity One UTF-8 text file, editable in any editor
Accessibility Humans read it; machines parse it
Decentralization Each person is a node; no central server can shut the network down
Org Philosophy Uses native Org Mode features—timestamps, properties, links—instead of inventing new syntax

2. Five-Minute Quick Start

2.1 Create the File

Open your editor and create social.org.

2.2 Add Your Profile

Paste the following and replace with your details:

#+TITLE: Alice's Micro-Blog
#+NICK: Alice
#+DESCRIPTION: Graphic designer who loves open-source tools
#+AVATAR: https://example.com/avatar.png
#+LINK: https://example.com

2.3 Start the Posts Section

Add one top-level heading:

* Posts

2.4 Publish Your First Post

Under * Posts, add:

**
:PROPERTIES:
:ID: 2025-08-15T09:00:00+08:00
:END:
Hello Org-social world!
  • ** creates a second-level Org headline—each headline is one post.
  • :ID: must be an RFC 3339 timestamp such as 2025-08-15T09:00:00+08:00.
  • Save with UTF-8 encoding and LF line endings.

2.5 Upload

Move the file to any static host. Your public URL could be:

https://example.com/social.org

Share that link—congratulations, you are now discoverable on the Org-social network.

3. Deep Dive: Syntax & Features

3.1 Global Metadata (Top of File)

Field Purpose Occurs
TITLE Title of your feed once
NICK Display name (no spaces) once
DESCRIPTION Short bio once
AVATAR URL to profile picture once
LINK Personal website or blog multiple allowed
FOLLOW Whom you follow; format: nick https://url/social.org multiple allowed
CONTACT Email, XMPP, Matrix, ActivityPub, etc. multiple allowed

Example:

#+LINK: https://alice.com
#+LINK: https://alice.com/portfolio
#+FOLLOW: bob https://bob.net/social.org
#+CONTACT: mailto:alice@example.com

3.2 Post Structure

Each post is a second-level headline (**) followed by a :PROPERTIES: drawer and the body text.

Required Property

  • ID—timestamp, unique per post.

Optional Properties

Property Meaning Example
LANG Language code en
TAGS Space-separated tags linux privacy
CONTENT_WARNING Flag sensitive content yes
CLIENT App you used to post org-social.el
REPLY_TO ID of the post you’re replying to https://bob.net/social.org/#2025-08-15T10:00:00+08:00
REPLY_URL Feed URL you’re replying to https://bob.net/social.org/
MOOD Emoji or short mood text 😊

3.3 Mentions

Define a custom link type once, then use it anywhere:

[[org-social:https://bob.net/social.org][bob]]

Inside a post:

**
:PROPERTIES:
:ID: 2025-08-15T11:00:00+08:00
:END:
Good morning [[org-social:https://bob.net/social.org][bob]] and [[org-social:https://carol.org/social.org][carol]].

3.4 Multi-line & Rich Content

Org Mode already supports:

  • Bullet lists
  • Bold *bold*, italic /italic/
  • Inline code ~printf("hi")~
  • Source blocks, images, PDF links, etc.

Example:

**
:PROPERTIES:
:ID: 2025-08-15T12:00:00+08:00
:END:
Today’s checklist:
- ✅ Publish Org-social guide
- ⏳ Write follow-up script

Here is a Bash snippet:
#+BEGIN_SRC bash
curl -L https://example.com/social.org
#+END_SRC

3.5 Polls

Create a * Polls headline (same file or a separate one). A poll post looks like:

* Polls

**
:PROPERTIES:
:ID: 2025-08-15T13:00:00+08:00
:POLL_END: 2025-08-15T15:00:00+08:00
:END:
Favorite editor?

- [ ] Emacs
- [ ] Vim
- [ ] VS Code

To vote, someone publishes a new post:

**
:PROPERTIES:
:ID: 2025-08-15T13:30:00+08:00
:REPLY_TO: https://example.com/social.org/#2025-08-15T13:00:00+08:00
:POLL_OPTION: Emacs
:END:
Emacs, obviously.

3.6 Media Attachments

Use standard Org links:

[[https://example.com/photo.jpg][Sunset]]
[[https://example.com/report.pdf][Annual Report PDF]]

4. Discovery & Following

Org-social is intentionally “off-grid.” There is no central directory. You find feeds the same way you find email addresses:

  • Friends share their URLs.
  • You see links on blogs, forums, chat rooms.
  • Community-maintained lists (e.g., registers.txt in the official repo) collect voluntary submissions.

Once you have a URL, add it to your file:

#+FOLLOW: dave https://dave.xyz/social.org

Then fetch the file manually or with a script/client to see Dave’s timeline.

5. Hosting Options

Any server that can serve plain UTF-8 text works.

Option Notes
GitHub Pages Push social.org to username.github.io
Netlify / Vercel Drag-and-drop deploy
Self-hosted Nginx One location block: types { } default_type "text/plain; charset=utf-8";
Gitea / Forgejo Upload as a raw file, copy raw URL

6. Updating or Deleting Posts

  • Edit: Change text, keep the same ID, upload again.
  • Delete: Remove the entire post or comment it out (# at start of each line).
  • Warning: Altering the ID creates a brand-new post and breaks existing replies.

7. Frequently Asked Questions (FAQ)

Q1. Do I have to use Emacs?

No. Any editor that saves UTF-8 with LF line endings works. Emacs simply gives the best Org Mode experience.

Q2. Can I make my feed private?

Technically yes—put it behind HTTP Basic Auth or on a private LAN. Standard Org-social clients expect public URLs.

Q3. Is there an official mobile app?

Not yet. The only official helper is org-social.el, an Emacs package that reads your follow list and merges timelines.

Q4. How often should I poll feeds?

Check the Last-Modified HTTP header. If it hasn’t changed, skip the download.

Q5. Can I use Org-social as an RSS replacement?

Absolutely. Publish article summaries like this:

#+TITLE: Weekly Dev Links
#+NICK: devlinks
* Posts
**
:PROPERTIES:
:ID: 2025-08-15T07:00:00+08:00
:TITLE: Understanding SQL Indexes
:URL: https://example.com/sql-indexes
:END:
A 5-minute visual guide to B-tree indexes.

Q6. Pagination?

Yes. Use HTTP Range Requests (Content-Range and Content-Length) so clients only fetch new bytes.

8. Cheat Sheet & Quick Reference

Task Snippet
Follow someone #+FOLLOW: nickname https://domain/social.org
Reply to post :REPLY_TO: https://url/#timestamp
Add language tag :LANG: en
Add content warning :CONTENT_WARNING: yes
Insert image [[https://url/pic.png][alt text]]
Create poll Checkbox list + :POLL_END:
Backup git add social.org && git commit -m "backup"

9. Final Thoughts

Org-social proves that social networking does not need megabytes of JavaScript or opaque algorithms. A single text file, a timestamp, and a URL are enough to speak to the world. If that sounds appealing, open your editor tonight and type:

#+TITLE: My First Org-social Post
#+NICK: you
* Posts
**
:PROPERTIES:
:ID: 2025-08-15T23:59:00+08:00
:END:
Hello, decentralized friends.

Upload it, share the link, and you are officially part of the network—no accounts, no ads, no strings attached.

Exit mobile version