124 lines
3.7 KiB
Markdown
124 lines
3.7 KiB
Markdown
# Gemfreely
|
|
|
|
*Main Repo: [Agnos.is Git][5]*
|
|
|
|
*Mirrored at [GitHub][4]*
|
|
|
|
Sync Gemini protocol Gemlogs to WriteFreely instances.
|
|
|
|
## 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 <STRIP_BEFORE_MARKER>
|
|
Remove all text BEFORE this marker in the Gemlog post
|
|
|
|
--strip-after-marker <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.
|
|
|
|
## Reporting Issues
|
|
|
|
Issues can be reported at either GitHub or the canonical repository at https://git.agnos.is/.
|
|
|
|
* [Agnos.is Git][5]
|
|
* [GitHub][4]
|
|
|
|
[1]: https://geminiprotocol.net/
|
|
[2]: https://writefreely.org/
|
|
[3]: https://en.wikipedia.org/wiki/ActivityPub
|
|
[4]: https://github.com/ProjectMoon/gemfreely
|
|
[5]: https://git.agnos.is/projectmoon/gemfreely
|