From bc7d23c830e1095f58984909ae44a4e3cb9dc385 Mon Sep 17 00:00:00 2001 From: Simon Repp Date: Sat, 3 May 2025 13:11:35 +0200 Subject: [PATCH] Document feeds option, extend site docs by separate sections per option --- docs/reference/01 Collection.md | 24 ++++++++++- docs/reference/02 Playlist.md | 26 ++++++++++-- docs/reference/04 Site.md | 72 ++++++++++++++++++++++++--------- src/collection.rs | 1 + src/playlist.rs | 1 + 5 files changed, 100 insertions(+), 24 deletions(-) diff --git a/docs/reference/01 Collection.md b/docs/reference/01 Collection.md index abd0f80..ee77a3e 100644 --- a/docs/reference/01 Collection.md +++ b/docs/reference/01 Collection.md @@ -37,7 +37,7 @@ Content in a collection currently appears in the following order on the built si ## The collection.eno manifest -> All options at a glance: [copy_link](#copy_link), [description](#description), [download](#download), [embedding](#embedding), [link](#link), [offline](#offline), [platform_integration](#platform_integration), [title](#title), [unlisted](#unlisted), [video_order](#video_order) +> All options at a glance: [copy_link](#copy_link), [description](#description), [download](#download), [embedding](#embedding), [feeds](#feeds), [link](#link), [offline](#offline), [platform_integration](#platform_integration), [title](#title), [unlisted](#unlisted), [video_order](#video_order) Manifest for tagging and configuring a collection. @@ -108,7 +108,7 @@ This allows visitors/you to copy embed codes (html) that they/you can use to embed your videos on their/your own sites. Embedding is disabled by default. If you want to enable it you also need to -set the site's base_url (embeds work by displaying something from your site +set the site's [base_url](site.html#base_url) (embeds work by displaying something from your site on another site, for this the other site needs to point to your site's address), and then set `embedding: enabled`, either at the collection, playlist or video level. If you set it `enabled` at the catalog or playlist @@ -119,6 +119,26 @@ specific playlists or videos. embedding: enabled ``` +## `feeds` + +Hyper 8 offers four different types of feeds on your site: + +- Atom +- Plain RSS +- Podcast RSS +- Media RSS + +Visitors can subscribe to the entire site (= to the root collection or +playlist) or to each subcollection and playlist on a site individually. + +Feeds are enabled by default if you specified your site's [base_url](site.html#base_url). + +To disable them: + +```eno +feeds: disabled +``` + ## `link` Any number of `link` fields can be given. The `label` for a link is optional. diff --git a/docs/reference/02 Playlist.md b/docs/reference/02 Playlist.md index 0fc7094..527ce80 100644 --- a/docs/reference/02 Playlist.md +++ b/docs/reference/02 Playlist.md @@ -22,7 +22,7 @@ Naturally, an empty playlist is not much of a playlist, so in reality you will have video directories inside the playlist directory as well, but note that the presence of video directories itself does not make the directory a playlist by itself, because by default a directory containing video -directories will be interpreted as a `Collection`. The `playlist.eno` +directories will be interpreted as a [Collection](collection.html). The `playlist.eno` manifest is thus mandatory for every playlist. Generally speaking, a playlist is a list of videos primarily intended for @@ -30,7 +30,7 @@ sequential playback. ## The playlist.eno manifest -> All options at a glance: [banner](#banner), [copy_link](#copy_link), [description](#description), [download](#download), [embedding](#embedding), [link](#link), [offline](#offline), [order](#order), [platform_integration](#platform_integration), [title](#title), [unlisted](#unlisted) +> All options at a glance: [banner](#banner), [copy_link](#copy_link), [description](#description), [download](#download), [embedding](#embedding), [feeds](#feeds), [link](#link), [offline](#offline), [order](#order), [platform_integration](#platform_integration), [title](#title), [unlisted](#unlisted) Manifest for tagging and configuring a playlist. @@ -116,7 +116,7 @@ This allows visitors/you to copy embed codes (html) that they/you can use to embed your videos on their/your own sites. Embedding is disabled by default. If you want to enable it you also need to -set the site's base_url (embeds work by displaying something from your site +set the site's [base_url](site.html#base_url) (embeds work by displaying something from your site on another site, for this the other site needs to point to your site's address), and then set `embedding: enabled`, either at the collection, playlist or video level. If you set it `enabled` at the catalog or playlist @@ -127,6 +127,26 @@ specific playlists or videos. embedding: enabled ``` +## `feeds` + +Hyper 8 offers four different types of feeds on your site: + +- Atom +- Plain RSS +- Podcast RSS +- Media RSS + +Visitors can subscribe to the entire site (= to the root collection or +playlist) or to each subcollection and playlist on a site individually. + +Feeds are enabled by default if you specified your site's [base_url](site.html#base_url). + +To disable them: + +```eno +feeds: disabled +``` + ## `link` Any number of `link` fields can be given. The `label` for a link is optional. diff --git a/docs/reference/04 Site.md b/docs/reference/04 Site.md index af5aa5e..7cee8a5 100644 --- a/docs/reference/04 Site.md +++ b/docs/reference/04 Site.md @@ -12,6 +12,8 @@ placed. ## The site.eno manifest +> All options at a glance: [base_url](#base_url), [deploy_config](#deploy_config), [disable_clean_urls](#disable_clean_urls), [language](#language), [poster_aspect](#poster_aspect), [theme](#theme) + Manifest for configuring the site. ```eno @@ -27,11 +29,46 @@ server = ssh-customer123.example.com user = customer123 ``` +## `base_url` + With `base_url` you configure at which (sub)domain (respectively also subdirectory if not at the root) your site will be hosted, which is used for rendering certain features and for verifying that the deployment settings are correct. +```eno +base_url: https://example.com +``` + +## `deploy_config` + +With `deploy_config` you can configure the (remote) `path`, `server` and `user` +for an ssh/rsync based deployment. Note that for now only password-less +(ssh public/private key) authentication is possible. In order to prevent +accidental deployments to wrong remote servers and paths, deployment requires +the `base_url` to be specified and the server to be set up so the contents +at `deploy_config.path` are already accessible through the public `base_url`. +(On deploment, Hyper 8 will do a test upload of a text file to the remote +path and check if it's accessible through the public url - if it isn't, the +file is removed and the deployment aborted). + +## `disable_clean_urls` + +With `disable_clean_urls` Hyper 8 can be instructed to create a build with +fullly verbose internal (file) linking, meaning that each link on the site +ends on `/index.html` instead of just `/` (e.g. `https://example.com/collection/index.html` +instead of `https://example.com/collection/`). Although this arguably looks +a little more raw, it has the advantage of links working in the widest range +of environments - especially it enables the build to be browseable directly +from disk without any webserver inbetween, which makes a lot of sense if +you're planning to archive your page somewhere offline. + +```eno +disable_clean_urls +``` + +## `language` + With `language` you can supply a language code (in BCP 47 format) that will identify the site's content for browsers and screenreaders. For supported languages (currently english and german - contributions welcome!) all @@ -40,6 +77,12 @@ implemented texts will show up as translated in the final website. The Hyper rudimentarily developed right now!), for this see the command line arguments documentation. +```eno +language: es +``` + +## `poster_aspect` + The `poster_aspect` option accepts either a numeric aspect ratio like `1.78`, or a dividend/divisor notation like `16/9` or `4:3`. On a Hyper 8 site, this controls the aspect ratios of video thumbnails everywhere. On an average @@ -47,6 +90,16 @@ site the default `16:9` aspect ratio is a good choice, but for wider cinematic material a wider aspect ratio is recommended, as is a portrait ratio like for instance `9:16` for exclusively mobile video content. +```eno +poster_aspect: 16:9 +``` + +## `theme` + +```eno +theme: adaptive_cool +``` + The `theme` option can be set to any of these: - `adaptive_cool`, - `adaptive_deep`, @@ -70,22 +123,3 @@ needs, but of course for specific usecases this can be weighed off - e.g. it might still make sense to configure a trailer page for a horror movie with a dark theme only, as the imagery might be dark itself and a light theme would potentially collide with the desired aesthetics and visual impression intended. - -With `deploy_config` you can configure the (remote) `path`, `server` and `user` -for an ssh/rsync based deployment. Note that for now only password-less -(ssh public/private key) authentication is possible. In order to prevent -accidental deployments to wrong remote servers and paths, deployment requires -the `base_url` to be specified and the server to be set up so the contents -at `deploy_config.path` are already accessible through the public `base_url`. -(On deploment, Hyper 8 will do a test upload of a text file to the remote -path and check if it's accessible through the public url - if it isn't, the -file is removed and the deployment aborted). - -With `disable_clean_urls` Hyper 8 can be instructed to create a build with -fullly verbose internal (file) linking, meaning that each link on the site -ends on `/index.html` instead of just `/` (e.g. `https://example.com/collection/index.html` -instead of `https://example.com/collection/`). Although this arguably looks -a little more raw, it has the advantage of links working in the widest range -of environments - especially it enables the build to be browseable directly -from disk without any webserver inbetween, which makes a lot of sense if -you're planning to archive your page somewhere offline. diff --git a/src/collection.rs b/src/collection.rs index 38f6219..7f0d1c2 100644 --- a/src/collection.rs +++ b/src/collection.rs @@ -38,6 +38,7 @@ const COLLECTION_OPTIONS: &[&str] = &[ "description", "download", "embedding", + "feeds", "link", "offline", "platform_integration", diff --git a/src/playlist.rs b/src/playlist.rs index ec8ede5..b5eafc0 100644 --- a/src/playlist.rs +++ b/src/playlist.rs @@ -34,6 +34,7 @@ const PLAYLIST_OPTIONS: &[&str] = &[ "description", "download", "embedding", + "feeds", "link", "offline", "order",