owl-blogs/README.md

123 lines
3.6 KiB
Markdown
Raw Permalink Normal View History

2022-08-15 19:06:17 +00:00
![Mascot](assets/owl.png)
2022-08-03 14:49:17 +00:00
# Owl Blogs
2022-11-01 21:00:01 +00:00
A simple web server for blogs generated from Markdown files.
**_This project is not yet stable. Expect frequent breaking changes! Only use this if you are willing to regularly adjust your project accordingly._**
2022-08-03 15:56:13 +00:00
## Repository
A repository holds all data for a web server. It contains multiple users.
## User
2022-08-08 20:17:03 +00:00
A user has a collection of posts.
2022-08-03 15:56:13 +00:00
Each directory in the `/users/` directory of a repository is considered a user.
### User Directory structure
```
<user-name>/
\- public/
\- <post-name>
2022-08-08 20:17:03 +00:00
\- index.md
2022-08-03 15:56:13 +00:00
-- This will be rendered as the blog post.
-- Must be present for the blog post to be valid.
-- All other folders will be ignored
2022-11-01 20:57:51 +00:00
\- incoming_webmentions.yml
-- Used to track incoming webmentions
\- outgoing_webmentions.yml
-- Used to track outgoing webmentions
2022-08-03 15:56:13 +00:00
\- media/
-- Contains all media files used in the blog post.
-- All files in this folder will be publicly available
2022-08-23 15:59:17 +00:00
\- webmention/
\- <hash>.yml
-- Contains data for a received webmention
2022-08-03 15:56:13 +00:00
\- meta/
\- base.html
-- The template used to render all sites
2022-11-01 20:57:51 +00:00
\- config.yml
-- Holds information about the user
2022-08-03 15:56:13 +00:00
\- VERSION
-- Contains the version string.
-- Used to determine compatibility in the future
2022-09-10 13:30:52 +00:00
\- media/
-- All this files will be publicly available. To be used for general files
2022-11-01 20:57:51 +00:00
\- avatar.{png|jpg|jpeg|gif}
-- Optional: Avatar to be used in various places
\- favicon.{png|jpg|jpeg|gif|ico}
-- Optional: Favicon for the site
```
### User Config
Stored in `meta/config.yml`
```
title: "Title of the Blog"
subtitle: "Subtitle of the Blog"
header_color: "#ff0000"
author_name: "Your Name"
me:
- name: "Connect on Mastodon"
url: "https://chaos.social/@h4kor"
- name: "I'm on Twitter"
url: "https://twitter.com/h4kor"
2022-08-08 20:17:03 +00:00
```
### Post
Posts are Markdown files with a mandatory metadata head.
- The `title` will be added to the web page and does not have to be reapeated in the body. It will be used in any lists of posts.
2022-11-01 20:57:51 +00:00
- `description` is optional. At the moment this is only used for the HTML head meta data.
2022-08-08 20:17:03 +00:00
- `aliases` are optional. They are used as permanent redirects to the actual blog page.
2022-11-01 20:57:51 +00:00
- `draft` is false by default. If set to `true` the post will not be accessible.
- `reply` optional. Will add the link to the top of the post with `rel="in-reply-to"`. For more infos see: [https://indieweb.org/reply](https://indieweb.org/reply)
2022-08-08 20:17:03 +00:00
```
---
title: My new Post
2022-11-01 20:57:51 +00:00
Description: Short text used in meta data (and lists in the future)
2022-08-15 05:31:19 +00:00
date: 13 Aug 2022 17:07 UTC
2022-08-08 20:17:03 +00:00
aliases:
- /my/new/post
- /old_blog_path/
2022-11-01 20:57:51 +00:00
draft: false
reply:
url: https://link.to/referred_post
text: Text used for link
2022-08-08 20:17:03 +00:00
---
Actual post
```
2022-09-04 13:03:16 +00:00
2022-11-01 20:57:51 +00:00
### Webmentions
This feature is not yet full supported and needs a lot of manual work. Expect this to change quiet frequently and breaking existing usages.
To send webmentions use the command `owl webmention`
2022-09-04 13:03:16 +00:00
2022-11-01 20:57:51 +00:00
Retrieved webmentions have to be approved manually by changing the `approval_status` in the `incoming_webmentions.yml` file.
2022-09-04 13:03:16 +00:00
2022-11-01 20:57:51 +00:00
#### incoming_webmentions.yml
```
- source: https://example.com/post
title: Example Post
approval_status: ["", "approved", "rejected"]
retrieved_at: 2021-08-13T17:07:00Z
```
#### outgoing_webmentions.yml
```
- target: https://example.com/post
supported: true
scanned_at: 2021-08-13T17:07:00Z
last_sent_at: 2021-08-13T17:07:00Z
2022-09-04 13:03:16 +00:00
```