Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/flancian/garden/llms.txt

Use this file to discover all available pages before exploring further.

Agora Protocol is a series of conventions that people can agree to follow when communicating for the common good. It is deliberately minimal: the baseline layer requires nothing beyond plain text, making it usable anywhere you can write — in a Markdown file, a wiki, an email, a social media post, or a book. Successive layers add expressive power through wikilinks, hashtags, and social actions, each building on the last without breaking compatibility with simpler layers.

​
Why a protocol

A shared protocol creates a common pattern language. When two people writing independently both link to [[distributed systems]], the Agora can recognize that they are writing about the same concept and surface both contributions together, without requiring them to coordinate in advance. The protocol is the minimal agreement that makes this possible.
Agora Protocol is intended to be fully optional at every layer. The default commitment level is opt-in. You participate in the parts that serve your goals.

​
Layer 0: plain text and structure

Layer 0 is the bootstrapping layer. It requires only plain text with indented bulleted lists. 
- A concept.
  - A related idea under it.
    - A further elaboration.
Indented lists express a heterarchy — a hierarchy without a fixed top — which is the structural foundation of Agora content. Any plain-text file using indented lists is already participating in Layer 0. This layer is intentionally compatible with adversarial interoperability: you can use it in any format or tool without asking permission from anyone.

​
Layer 1: wikilinks and hashtags

Layer 1 adds wikilinks and hashtags on top of plain text. These are the primary linking mechanisms in the Agora.

​
Wikilinks

A wikilink connects your note to a node in the Agora by topic name: 
[[distributed systems]]
[[knowledge commons]]
[[agora protocol]]
When the Agora server resolves a wikilink, it finds all subnodes — notes from all contributors — that correspond to that topic name and displays them together at a single URL.

​
Hashtags

Hashtags work as both topic markers and social actions: 
#distributed-systems
#knowledge-commons
The Agora has limited but meaningful hashtag support, treating #topic as equivalent to [[topic]] for linking purposes.

​
Social actions

Beyond linking, the protocol defines a small set of social action hashtags that change how content is assembled at a node.

​
#pull

Pull another node’s content into the current node at render time: 
#pull [[agora protocol]]
#pull [[knowledge commons]]
This lets you transclude related nodes without copying text, keeping the source of truth in one place.

​
#push

Push content from the current node into another node: 
#push [[agora]]
  - an [[agora]] is a seed that wants to grow into a tree.
  - the [[seed]] of this agora is [[go/agora/git]], defining a [[commons]].
The indented content below #push [[target]] appears as a contribution to that target node from the current subnode.

​
#go

#go creates an intent link — a declared redirect from the current node to a URL or another node: 
#go https://github.com/flancian/agora
#go [[git]]
When the Agora resolves a node that contains #go, it surfaces the target as a destination the node’s author intends you to visit.
You can combine actions. For example, #pull [[agora protocol]] in your notes will transclude the community’s shared definition of the protocol into your own node when viewed through the Agora.

​
Federation across agoras

The protocol is designed to enable federation. Compatible agoras are expected to assemble into a greater federated Agora network where they can fork and merge content as needed.
Each Agora publishes a set of definitions of intention as expressed by its users. Compatible agoras exchange Agora Protocol payloads — collections of plain text with wikilinks and social actions — and can resolve each other’s node references. Extensions to the protocol are proposed and settled through Agora RFCs, maintained as a community-governed document.
It is the opinion of this Agora that using Agora Protocol in a medium defines an Agora: it designates that context as part of some Agora and marks the medium as potentially interoperable with the Agora network. Any agora must communicate clear goals; compatible agoras must not change the CONTRACT in ways that break interoperability.
Successive layers beyond Layer 1 are explicitly discussed through Agora RFCs and settled through a governance layer defined by community convention. The community stoa at stoa.anagora.org/p/stoa maintains the communally agreed text of the full protocol.

​
Where you can use it

Because Layer 0 requires only plain text and Layer 1 requires only common markup conventions, Agora Protocol is already in use across many contexts:
  • Digital gardens — Markdown files in Git repositories
  • Wikis — wikilinks are already a native concept
  • Email — plain text plus hashtags
  • Chat and social networks — via Agora Bridge bots on Mastodon and Twitter
  • Books — Markdown manuscripts with wikilinks
  • Around the web — via browser extensions and integrations

Build docs developers (and LLMs) love

Get started for freeTalk to us