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)

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)

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

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.

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

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.