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.

The agora.yaml file is a per-user configuration file you can add to the root of your digital garden repository. Its presence signals to any Agora instance that you want your garden integrated, and its contents let you customise that integration — specifying bridges, actions, and how your notes interact with the rest of the Agora network. Adding agora.yaml is not required to participate in the Agora. Basic participation only requires publishing your garden and submitting a PR to gardens.yaml. The agora.yaml file unlocks more advanced configuration and is particularly relevant if you run your own Agora instance or want to configure bridge integrations.

​
Where to place the file

Put agora.yaml in the root directory of your digital garden repository — the same level as your notes. The Agora bridge looks for it at this location when it processes your garden. 
my-garden/
├── agora.yaml        ← configuration file goes here
├── index.md
├── climate-change.md
└── reading-list.md

​
What the file does

The agora.yaml file serves two related purposes:

Signal integration intent

Having an agora.yaml in a public repository signals to any Agora instance that you intend to integrate with it. It is a machine-readable declaration of participation.

Configure your integration

The file’s contents let you specify bridges, actions, and other per-user settings that control how the Agora processes and presents your garden.

​
Annotated example

The following is an annotated agora.yaml based on the reference format used by Agora maintainers. Most fields are optional; you can include only what you need. 
# agora.yaml
# Place this file in the root of your digital garden repository.
#
# Having this file in a public repository signals an intent to integrate
# with any Agora that discovers it.

# Your Agora username. This is how your contributions are attributed.
# Should match the 'user' field in gardens.yaml if you have submitted a PR.
# user: your-username

# The format of your notes. 'markdown' is the default.
# Other supported values: 'org', 'plain'
# format: markdown

# Bridge configuration.
# Bridges connect your garden to external services for input or output.
# See the bridge documentation for the full list of available bridge types.
# bridges:
#   - type: git
#     url: https://github.com/YOUR_USERNAME/YOUR_REPO
#     direction: input   # 'input', 'output', or 'bidirectional'

# Agora actions.
# Actions are operations the Agora can perform on your behalf,
# such as rendering nodes or triggering syncs.
# actions: []
As of early 2023, agora.yaml support is still being actively developed. The fields above reflect the intended design. If you have questions about what is currently supported, reach out in the Agora chat room.

​
Relationship to gardens.yaml

agora.yaml and gardens.yaml work at different levels:
FileLocationPurpose
gardens.yamlAgora repository (community-maintained)Tells the Agora which gardens exist and where to find them.
agora.yamlYour garden repository (you maintain)Tells the Agora how you want your specific garden integrated and configured.
You do not need agora.yaml to be listed in gardens.yaml. But if you are listed in gardens.yaml and also have agora.yaml, the Agora will use your agora.yaml settings when processing your garden.

​
Bridge configuration

Bridges are services that move content into and out of an Agora. They are managed by the Agora Bridge service and configured with YAML. The main configuration file for the bridge service is bridges.yaml, which is maintained separately by whoever runs the Agora instance. Your agora.yaml can request specific bridge behaviour for your garden.
As of 2022, the Agora Bridge supports the following input sources:
  • Git — pulls from a public Git repository (the default)
  • Federated Wiki — ingests content from FedWiki instances
  • Mastodon — pulls posts from a Mastodon account
  • Twitter/X — pulls posts from a Twitter account
Output bridges write content back to a filesystem via git pull. Bridges can be configured as input, output, or bidirectional.
The Flancia Collective runs the bridge service for the main Agora at anagora.org. If you are running your own Agora instance, you run your own bridge service and configure it with your own bridges.yaml.
When the Agora bridge processes your garden (as listed in gardens.yaml), it checks for an agora.yaml file at the root of your repository. If it finds one, it reads your settings and applies them during integration. The bridge honours your configuration file automatically — you do not need to notify anyone after adding or updating it.

​
Next steps

Publish your garden

Register your garden with the Agora by submitting a PR to gardens.yaml.

Agora Bridge

Learn how the bridge service ingests content from different sources and how to configure it for your own Agora instance.

Build docs developers (and LLMs) love

Get started for freeTalk to us