Welcome to Filo

Filo is a simple, federated, file-based social system — made for humans, not algorithms.

Here, everything begins with a plain text file.

You write notes, journal entries, ideas, stories, or articles — in your own folder, your own way.

Then you list them in a small file called filo.txt, and just like that, the world can follow your thoughts.

No databases. No signups. No centralized servers.

Just readable text, a few conventions, and the quiet power of federation.

Whether you’re a writer, a coder, a dreamer, or a curious mind —

Filo gives you a space to express yourself, share knowledge, and connect across the open web.

📄 filo.txt — The Heart of Your Filo Presence

Every Filo user or instance must publish a filo.txt file.

This plain text file acts as your personal index — listing your entries and making them discoverable to others.

It is intentionally simple, easy to read, and trivial to parse.

📌 File Format

🧷 Header (required)

The first lines of filo.txt contain metadata about your feed, each on a separate line, using key-value format.

title: My Filo Feed
self: https://example.com/filo.txt
profile: https://example.com/profile.yaml
updated: 2025-04-15T14:32:00Z

• title: – A short, human-readable name for your feed
• self: – The full URL of this filo.txt file
• profile: – (Optional) Link to your profile.yaml with more details about you
• updated: – The timestamp of the last update in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)

👉 There must be a blank line between the header and the list of entries.

🧾 Entry Lines

Each line after the header represents one entry in your Filo presence.

🔹 General Format:

[TIMESTAMP] [+TYPE] [#TAGS...] LINK [TITLE or SHORT TEXT]

• TIMESTAMP – Optional but recommended (YYYY-MM-DDTHH:MM:SSZ)
• +TYPE – Content type (like +note, +diary, +knowledge, +story, +zine, etc.)
• #TAGS – Optional tags, prefixed by #
• LINK – Full URL to the entry file
• TEXT – Optional: short title or summary text

🔸 Examples

2025-04-15T08:00:00Z +diary #life #faith https://webdad.eu/journal/2025-04-15.txt A new morning begins
2025-04-14T18:34:22Z +knowledge #federation https://webdad.eu/notes/federation.txt Federation Made Simple
https://webdad.eu/notes/simple-entry.txt
2025-04-13T12:10:00Z +note https://webdad.eu/notes/quick.txt

• You can include as much or as little as you want.
• If you prefer total simplicity, just the link is enough.
• More structured entries help others parse and present your content better.

✅ Summary

• filo.txt is required.
• It begins with a header block (with keys like title, self, profile, updated)
• Followed by a blank line
• Then one entry per line — newest at the bottom
• All files listed here are considered public parts of your Filo presence

👤 profile.yaml  — Your Public Identity

The profile.yaml file describes the author or node behind a filo.txt file.

It’s a simple, optional YAML file that helps others display your content in a human-friendly way.

💡 This file is referenced in the profile: field of filo.txt.

📄 Location

Place profile.yaml anywhere you’d like — typically in the same directory as filo.txt.

Its URL must be declared in your filo.txt header like this:

profile: https://example.com/profile.yaml

✅ Required Fields

None. profile.yaml is optional and all fields inside it are optional.

However, it is strongly recommended for human identity and interoperability.

🧷 Recommended Fields

Here are common fields you can include:

nick: webdad
name: Dominik Sigmund
description: Tinkerer of tools and thoughts.
url: https://webdad.eu/
avatar: https://webdad.eu/avatar.png
location: Germany
public_key: abcdef1234567890
created: 2025-04-15T14:00:00Z

Field Guide

🛠️ Extensibility

You can add any additional fields you need. Clients should ignore unknown fields gracefully.

This allows for experimentation and growth — such as:

projects:
  - name: Filo
    url: https://filo.social/
  - name: WebDad Radio
    url: https://fortressofrock.com/

✅ Summary

• profile.yaml helps people and clients recognize who you are.
• It’s human-readable, extensible, and completely optional.
• Link to it from your filo.txt using the profile: field.

📝 Entry Types in Filo

In Filo, each entry is a standalone plain text or Markdown file.

It can be as simple as raw text, or include YAML frontmatter for richer metadata.

Each entry listed in filo.txt may have a +type, but types are optional.

If no +type is given, or the file has no frontmatter, the entry is still valid and treated as generic content.

🔄 Shared Conventions

• All entries may begin with a YAML frontmatter block (— to start and end).
• YAML is parsed if present. Otherwise, the file is treated as pure text.
• Unknown fields are ignored — extensibility is encouraged.

✨ Generic Entry (no frontmatter)

This is the most minimal form: just content, no metadata.

Just some thoughts I wanted to share. No frontmatter here.

Used when:

• filo.txt line contains only a link or a simple +note
• No YAML frontmatter is provided

The entry is valid as-is. It’s still indexable and readable.

✅ Defined Entry Types

Each type may be used in filo.txt with a +type prefix. These types guide how clients interpret and display the content.

You can always use custom types, clients should then ignore them.

🔹 +note

Short, informal thoughts, ideas, or observations — similar to microblog posts.

---
type: note
created: 2025-04-14T17:22:00Z
tags: [idea, simplicity]
---
I still believe the best tech is invisible.

🔹 +diary

Personal journal entries, reflections, and logs.

---
type: diary
date: 2025-04-15T08:00:00Z
tags: [faith, morning]
---
The sunrise today was gentle. I took a long breath and smiled.

🔹 +knowledge

Evergreen notes or evolving pages meant to inform, explain, or collect knowledge.

---
type: knowledge
title: Federation Made Simple
created: 2025-04-14T18:34:00Z
updated: 2025-04-15T09:12:00Z
tags: [federation, design]
---
Here’s how to build a federated system using only plain text files and index lists...

• updated is optional but recommended
• title helps display in knowledge readers

🔹 +story

Creative fiction, serialized narratives, or branching adventures.

---
type: story
title: The Fork in the Forest
created: 2025-04-01T16:00:00Z
choices:
  - text: Go left
    link: https://example.com/story/left-path.txt
  - text: Go right
    link: https://example.com/story/right-path.txt
---
The path split beneath my feet. I had to choose.

• choices allows for interactive storytelling (optional)

🔹 +zine

Curated bundles — collections of thoughts, articles, poetry, art, or anything else. Often published periodically.

---
type: zine
title: The Void Zine — Issue #1
issue: 1
published: 2025-04-01T10:00:00Z
tags: [zine, writing, culture]
---
Welcome to the first issue of *The Void*, a Filo-native zine exploring solitude and the self.

🧩 Extensibility

You can define new types freely (e.g. +code, +question, +quote, +project) — just follow the YAML format.

Clients should gracefully fall back to generic display behavior if they don’t recognize a type.

✅ Summary

• Type is optional in both filo.txt and entry files.
• No frontmatter? It’s still valid and readable — just plain text.
• Known types (+note, +diary, +knowledge, etc.) allow richer structure and display.
• Frontmatter adds structure; files without it are still welcome.

🚧 Roadmap

Filo is being built step by step — openly, transparently, and file-first.

Here’s what’s already working, and what’s still to come:

✅ What’s Already Defined

• filo.txt index format – clean, human-readable structure
• Entry types – +note, +diary, +knowledge, +story, +zine, and generic entries
• Optional profile.yaml – identity, metadata, extensibility
• No Git, no servers required – just plain files, served however you like

🧭 In Progress

🛜 Federation & Discovery

• How do Filo instances find and follow each other?
• Planned: pull-based federation with optional pings, caching, and link-following
• Idea: passive discovery by linking to another user’s filo.txt

🧰 Filo CLI (in Go)

• Create and manage filo.txt and entries
• Entry templates per type
• Auto-update updated: timestamp
• Federation helpers (e.g. fetch others, follow list)

🌐 Public Registry (PHP)

• Optional public listing of Filo feeds
• Allows others to browse and discover new feeds
• Periodically verifies links and caches profile/index metadata
• Possible profile claims / verification

🔌 WordPress Plugin

• Generate filo.txt and profile.yaml from posts
• Mark posts as public Filo entries with custom fields or tags
• Auto-update on post publish/update
• Optional shortcodes to display Filo follows or feed items

🔮 Planned / To Explore

🗂️ Reference Feed Support

• Optional follows.txt or subscriptions.txt
• Helps users define who they follow or recommend

💬 Replies, Mentions, Reactions

• Simple way to link one entry to another (via in-reply-to: or backreferences)
• Possibly implemented via additional entry types (+reply, +like, etc.)

🖼️ Media Handling

• Best practices for including images, audio, or video
• Light frontmatter like media: or Markdown-native embedding

🌿 Visual Reader UI

• A simple, elegant Filo browser
• Local following & reading
• Filter by type, tag, date

🧩 Ecosystem Tools

• Browser extension (e.g. Filo-aware feed reader)
• Static site generator adapter
• Offline/desktop viewer

🤝 Contributing to Filo

Filo is an open and growing project — built on simplicity, shared ideas, and human-first design.

Whether you have an idea, a bug to report, a new entry type to suggest, or want to build tools in the ecosystem — you’re invited to shape Filo’s future.

💡 How to Contribute

For now, contributing is intentionally as low-barrier as the project itself:

• 📧 Send your suggestions via email: 👉 filo@webdad.eu

Feel free to propose:

• New entry types and their metadata
• Changes or refinements to the format
• Ideas for federation, tools, or plugins
• Use cases, example setups, or improvements to docs

🛠️ Planned: GitLab Move

Soon, Filo will move to a public GitLab repository for:

• Issues
• Discussions
• Specs
• Reference tools (CLI, registry, plugins)

You’ll be able to fork, merge, and collaborate the usual way — or still just email us your thoughts.

🧭 Philosophy

Filo is for humans first.

We keep things:

• Understandable – Everything in plain text
• Portable – No lock-in, no platform dependency
• Open-ended – You can build your own Filo and expand it freely

There’s no gatekeeping here. Your voice matters.

🌱 Code of Conduct

Filo is a space for people to think, share, and create — simply and openly.

To keep it welcoming for everyone, we ask all contributors and participants to follow this Code of Conduct.

💬 Be Kind

Treat others with respect, patience, and empathy.

Disagreeing is okay — being dismissive, rude, or hostile is not.

🧑‍🤝‍🧑 Be Inclusive

Filo welcomes people of all backgrounds, abilities, and identities.

That includes (but is not limited to) people of all:

• Races, ethnicities, and nationalities
• Genders and gender identities
• Sexual orientations
• Belief systems and philosophies
• Abilities, neurotypes, and experiences

Make space for each other. Use inclusive language. Be mindful of assumptions.

🌍 Be Transparent

We believe in openness — in ideas, in process, and in feedback.

If you have a concern, a suggestion, or a disagreement, share it constructively.

We’re all here to build something better, together.

✋ Zero Tolerance

We do not tolerate:

• Harassment or discrimination
• Hate speech, personal attacks, or threats
• Gatekeeping or exclusionary behavior
• Any form of abuse, online or offline

If someone makes you feel unsafe or unwelcome, please reach out to filo@webdad.eu.

🤝 Let’s Build Thoughtfully

Filo isn’t about likes or followers. It’s about ideas, stories, and simple tools that bring people together.

Let’s keep this space thoughtful, low-noise, and kind to future readers.

We’ll adapt and improve this Code of Conduct as the project grows.

Thanks for being part of something human.