diff --git a/README.md b/README.md index 88c09ad..a932ef6 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,110 @@ +# Gemfreely + Sync Gemini protocol Gemlogs to WriteFreely instances. -Readme coming soon (TM). +## Prerequisites, and who is this for? + +To use `gemfreely`, You will need: + +* A gemini capsule. See [geminiprotocol.net][1]. +* A WriteFreely instance. See [writefreely.org][2]. + +`gemfreely` is for people who want to link their Gemini capsule's +gemlog into the Fediverse in a simple way. Gemini as a protocol is not +so easily accessible to most who use the internet, and with the +Fediverse gaining traction daily, this provides a way to increase the +visibility of your Gemini capsule's blog posts. + +[What is Gemini?][1] Gemini is a lightweight alternative to the +regular Web, but not designed to replace it. + +[What is WriteFreely?][2] WriteFreely is blogging software, similar to +WordPress, that integrates with the so-called "Fediverse" +(interconnected social media sites using the [ActivityPub][3] +standard). + +## Usage + +``` +gemfreely help +``` + +Gemfreely is designed to be straightforward to use, and is mostly +intended for use in an automated fashion. There are two steps to +successfully synchronizing your gemlog to WriteFreely: + +1. `gemfreely login` +2. `gemfreely sync` + +### WriteFreely Login + +First, you must possess an access token to your WriteFreely instance. +If you do not have one, `gemfreely` can create one for you: + +``` +gemfreely login --wf-url="https://witefreely.example.com/" -u yourusername -p "yourpassword" +``` + +If your login is successful, this will print out the WriteFreely +access token. Save this for use, as it is not stored anywhere. + +### Sync Gemlog to WriteFreely + +To synchronize your gemlog to WriteFreely, use the `sync` command. You will need: + +* Your WriteFreely access token. **Note:** Username and password are + *not* supported for sync. +* The full URL to your gemlog's feed (either Atom or Gemfeed, but Atom + is preferable for publish date accuracy). +* The URL of your writefreely blog. + +``` +gemfreely \ + -t "YourWFAccessToken" \ + --wf-alias="yourusername" \ + sync \ + --gemlog-url="gemini://example.com/gemlog/atom.xml" \ + --wf-url="https://writefreely.example.com" +``` + +The `--wf-alias` argument, in WriteFreely terms, is the `alias` of +your WriteFreely `collection`. In more common terms, this is the +identifier of your blog, and it's usually the same as your WriteFreely +username. + +#### Additional Options + +The `sync` command has two additional options relating to sanitization +of the converted gemlog posts: + +``` +--strip-before-marker + Remove all text BEFORE this marker in the Gemlog post + +--strip-after-marker + Remove all text AFTER this marker in the Gemlog post +``` + +These markers can be any valid UTF-8 string. The primary purpose of +these options is to remove text that is present in the gemlog post, +but doesn't need to be in the converted blog post in Markdown. On my +gemlog, it is used to remove the title, footer, and header, which contain +links to go back to other parts of the Gemini capsule. These don't +need to be present in the WriteFreely post. + +### Logout + +It is possible to invalidate the WriteFreely access token by using `gemfreely logout`: + +``` +gemfreely --wf-alias="youralias" + \ -t "YourAccessToken" logout \ + --wf-url="https://writefreely.example.com" +``` + +This will revoke the access token on WriteFreely, and a new one will +be required to use the `sync` command. + +[1]: https://geminiprotocol.net/ +[2]: https://writefreely.org/ +[3]: https://en.wikipedia.org/wiki/ActivityPub