Quick tutorial to get started on Org Social

Org Social is a very peculiar decentralized social network, as it works from text files in Org Mode format. Each user interacts through their own social.org file, which they modify with their favorite editor. In this plain text file, you create posts, participate in conversations, leave comments in groups, react, create polls, vote, and much more. All this without depending on a centralized server, without algorithms deciding what you see, without registration, always with total control of your content.

How does it work?

An Org Mode file doesn't have the ability to communicate with other files by itself. To make the magic of Org Social happen, several elements need to work together in perfect harmony:

• The social.org file: Where you and your posts live.
• A web hosting service: Where you upload your file so others can read it (for example, GitHub Pages, Cloudflare Pages, etc.) or any web server (Nginx, Apache, etc.). You also have host.org-social.org available.
• A domain or public URL: The web address where your file is located (for example, https://my-domain.com/social.org). host.org-social.org provides you with a public URL automatically.
• An Org Social client (org-social.el, for example): Responsible for reading the social.org files of other users you follow, and creates the timeline with their posts, replies, etc.
• A relay (optional): A service that indexes public social.org files so clients can easily discover new users and be notified if strangers interact with you. If you use org-social.el, this step is done automatically; you can ignore it.

Therefore, for someone to read your latest post, the following happens:

flowchart TD
    A[User creates social.org] --> B[Upload social.org to a web hosting service]
    B --> C[The social.org file is available at a public URL]
    C --> D[Another user uses a client org-social.el]
    D --> E[The client downloads social.org from the public URL]
    E --> F[The client displays the posts in the user's timeline]

1. You add a post to your social.org file using your text editor (Emacs, for example).
2. You upload the modified file to a web hosting service or sync with host.org-social.org.
3. Another user, who is following you, opens their client (like org-social.el in Emacs).
4. The client downloads your social.org file from the public URL where you hosted it, and all the other users they follow.
5. The client generates a timeline with all the posts, replies, etc., (similar to X/Twitter, Mastodon, etc.) for the user using it. And among those posts will be yours.

To read their posts, the process is the same but in reverse.

Just plain text files and public links! All the syntax that the client understands, the Relay processes, and you write is called Social Org.

Are you ready to get started?

Step 1: Register on a hosting service

You need to put your future social.org on the Internet so others can read it. To do this, you should use a web hosting service (GitHub Pages, Cloudflare Pages, etc.) or your own web server (Nginx, Apache, etc.). However, there's a faster alternative: host.org-social.org, a free service for hosting social.org files that will simplify your first steps and interactions with other users.

Go to https://host.org-social.org/signup and register with an alias you like. Warning! You won't be able to change it once created.

Write down VERY CAREFULLY the VFile Token and the Public URL that are provided to you. You won't be able to recover them if you lose them and they are essential to not lose your account.

Step 2: Install and configure org-social.el

Now comes the fun part: installing the Emacs client for Org Social. This client will allow you to read posts from other users and easily create new posts among many other functions.

M-x package-install RET org-social RET

In your Emacs configuration, add:

(setq org-social-file "YOUR VFILE")
(setq org-social-relay "https://relay.org-social.org/")
(setq org-social-my-public-url "YOUR PUBLIC URL")

And change:

• YOUR VFILE to the token you were given at host.org-social.org
• YOUR PUBLIC URL to the public URL you were given at host.org-social.org

Don't modify org-social-relay. Perhaps in the future you can change it if you use another relay, but for now leave it as is.

Now restart Emacs or evaluate those lines so the changes take effect.

Step 3: Create your first post

The time has come to interact with the Org Social network. Let's create your first post.

In Emacs, run:

M-x org-social-timeline

This will open the Org Social interface without much content, since you're not following anyone yet.

Now:

1. Press n (for "new post") or click the "New Post" button in the top bar. A new Org buffer will open so you can write your post.
2. Write your message, for example: "Hello Org Social!"
3. Save the buffer with Ctrl + x and then Ctrl + s

Take the opportunity to configure your profile. Edit these lines at the beginning of the social.org file with your data:

#+TITLE: My journal on Org Social
#+NICK: YourNickWithoutSpaces
#+DESCRIPTION: I'm new to Org Social. I like [your interests here]

Save again: Ctrl + x and then Ctrl + s.

You now have your first post created! It will automatically upload your social.org file to host.org-social.org, register you on the network (Relay), and other users will be able to read you. Try opening your public URL in a web browser to see your social.org file.

Step 4: Follow other users

Now that you have your profile working, it's time to discover other users.

Click on "Discover" in the top bar to see a list of users. You can follow any of them by clicking the "Follow" button next to their name or by adding their URL in the header of your social.org file with the following syntax:

#+TITLE: Bob's journal
#+NICK: Bob
#+FOLLOW: https://alice.com/social.org
#+FOLLOW: myBestFriend https://jane.com/social.org

You can open your file at any time with org-social-open-file.

Next steps

Now that you have the basics, you can explore:

• Create polls
• Join groups
• Use mentions to tag other users
• Post with rich formatting (tables, code, images)
• Have a personal blog (with its own RSS feed)

The important thing is that you keep experimenting and having fun with Org Social. Welcome to the community!