From 6c7cf7d9b5f2faec03fe75881b5ec81e0ac851fd Mon Sep 17 00:00:00 2001 From: Henry Jameson Date: Sun, 31 Mar 2019 15:32:11 +0300 Subject: some initial documentation about configuration --- docs/CONFIGURATION.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 docs/CONFIGURATION.md (limited to 'docs/CONFIGURATION.md') diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md new file mode 100644 index 00000000..5bb65aa1 --- /dev/null +++ b/docs/CONFIGURATION.md @@ -0,0 +1,85 @@ +# Pleroma-FE configuration and customization for instance administrators + +* *For user configuration, see USER_GUIDE.md* +* *For local development server configuration, see HACKING.md* + +## Where configuration is stored + +PleromaFE gets its configuration from several sources, in order of preference (the one above overrides ones below it) + +1. `/api/statusnet/config.json` - this is generated on Backend and contains multiple things including instance name, char limit etc. It also contains FE/Client-specific data, PleromaFE uses `pleromafe` field of it. For more info on changing config on BE, look [here](https://git.pleroma.social/pleroma/pleroma/blob/develop/docs/config.md#frontend_configurations) +2. `/static/config.json` - this is a static FE-provided file, containing only FE specific configuration. This file is completely optional and could be removed but is useful as a fallback if some configuration JSON property isn't present in BE-provided config. It's also a reference point to check what default configuration are and what JSON properties even exist. In local dev mode it could be used to override BE configuration, more about that in HACKING.md. File is located [here](https://git.pleroma.social/pleroma/pleroma-fe/blob/develop/static/config.json). +3. Built-in defaults. Those are hard-coded defaults that are used when `/static/config.json` is not available and BE-provided configuration JSON is missing some JSON properties. ( [Code](https://git.pleroma.social/pleroma/pleroma-fe/blob/develop/src/modules/instance.js) ) + +## Instance-defaults + +Important note that some configurations are treated as "instance default" - it means user is able to change this configuration for themselves. Currently, defaults are only applied for new visitors and people who haven't changed the option in question. If you change some instance default option, there is a chance it won't affect some users. + +There's currently no mechanism for user-settings synchronization across several browsers, *user* essentially means *visitor*, most user settings are stored in local storage/IndexedDB and not tied to an account in any way. + +## Options + +### `theme` +Default theme used for new users. De-facto instance-default, user can change theme. + +### `background` +Default image background. Be aware of using too big images as they may take longer to load. Currently image is fitted with `background-size: cover` which means "scaled and cropped", currently left-aligned. De-facto instance default, user can choose their own background, if they remove their own background, instance default will be used instead. + +### `logo`, `logoMask`, `logoMargin` +Instance `logo`, could be any image, including svg. By default it assumes logo used will be monochrome-with-alpha one, this is done to be compatible with both light and dark themes, so that white logo designed with dark theme in mind won't be invisible over light theme, this is done via [CSS3 Masking](https://www.html5rocks.com/en/tutorials/masking/adobe/). Basically - it will take alpha channel of the image and fill non-transparent areas of it with solid color. If you really want colorful logo - it can be done by setting `logoMask` to `false`. + +`logoMargin` allows you to adjust vertical margins between logo boundary and navbar borders. The idea is that to have logo's image without any extra margins and instead adjust them to your need in layout. + +### `redirectRootNoLogin`, `redirectRootLogin` +These two settings should point to where FE should redirect visitor when they login/open up website root + +### `chatDisabled` +unused (?) + +### `showInstanceSpecificPanel` +This allows you to include arbitrary HTML content in a panel below navigation menu. PleromaFE looks for an html page `instance/panel.html`, by default it's not provided in FE, but BE bundles some [default one](https://git.pleroma.social/pleroma/pleroma/blob/develop/priv/static/instance/panel.html). De-facto instance-defaults, since user can hide instance-specific panel. + +### `scopeOptionsEnabled` +TODO deprecated in !633 + +### `formattingOptionsEnabled` +Enables rich text formatting (broken?) + +### `collapseMessageWithSubject` +Collapse post content when post has a subject line (content warning). Instance-default. + +### `scopeCopy` +Copy post scope (visibility) when replying to a post. Instance-default. + +### `subjectLineBehavior` +How to handle subject line (CW) when replying to a post. +* `"email"` - like EMail - prepend `re: ` to subject line if it doesn't already start with it. +* `"masto"` - lime Mastodon - copy it as is. +* `"noop"` - do not copy +Instance-default. + +### `postContentType` +Default text formatting option (????) + +### `alwaysShowSubjectInput` +`true` - will always show subject line input, `false` - only show when it's not empty (i.e. replying). To hide subject line input completely, set it to `false` and `subjectLineBehavior` to `"noop"` + +### `hidePostStats` and `hideUserStats` +Hide counters for posts and users respectively, i.e. hiding repeats/favorites counts for posts, hiding followers/friends counts for users. + +### `loginMethod` +`"password"` - show simple password field +`"token"` - show button to loken with a token (??????) +TODO more info about token login needed + +### `webPushNotifications` +Enables [PushAPI](https://developer.mozilla.org/en-US/docs/Web/API/Push_API) - based notifications for users. Instance-default. + +### `noAttachmentLinks` +TODO ????? + +### `nsfwCensorImage` +Use custom image for NSFW'd images + +### `showFeaturesPanel` +Show panel showcasing instance features/settings to logged-out visitors -- cgit v1.2.3-70-g09d2 From bda36c64c0bd7a6a3beb80bc986ca6ac035d6761 Mon Sep 17 00:00:00 2001 From: Henry Jameson Date: Sun, 16 Jun 2019 21:53:00 +0300 Subject: User guide + updates --- docs/CONFIGURATION.md | 13 +++------- docs/USER_GUIDE.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+), 10 deletions(-) create mode 100644 docs/USER_GUIDE.md (limited to 'docs/CONFIGURATION.md') diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 5bb65aa1..bebf8c3b 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -39,12 +39,6 @@ unused (?) ### `showInstanceSpecificPanel` This allows you to include arbitrary HTML content in a panel below navigation menu. PleromaFE looks for an html page `instance/panel.html`, by default it's not provided in FE, but BE bundles some [default one](https://git.pleroma.social/pleroma/pleroma/blob/develop/priv/static/instance/panel.html). De-facto instance-defaults, since user can hide instance-specific panel. -### `scopeOptionsEnabled` -TODO deprecated in !633 - -### `formattingOptionsEnabled` -Enables rich text formatting (broken?) - ### `collapseMessageWithSubject` Collapse post content when post has a subject line (content warning). Instance-default. @@ -59,7 +53,7 @@ How to handle subject line (CW) when replying to a post. Instance-default. ### `postContentType` -Default text formatting option (????) +Default post formatting option (markdown/bbcode/plaintext/etc...) ### `alwaysShowSubjectInput` `true` - will always show subject line input, `false` - only show when it's not empty (i.e. replying). To hide subject line input completely, set it to `false` and `subjectLineBehavior` to `"noop"` @@ -69,14 +63,13 @@ Hide counters for posts and users respectively, i.e. hiding repeats/favorites co ### `loginMethod` `"password"` - show simple password field -`"token"` - show button to loken with a token (??????) -TODO more info about token login needed +`"token"` - show button to log in with external method (will redirect to login form, more details in BE documentation) ### `webPushNotifications` Enables [PushAPI](https://developer.mozilla.org/en-US/docs/Web/API/Push_API) - based notifications for users. Instance-default. ### `noAttachmentLinks` -TODO ????? +**TODO Currently doesn't seem to be doing anything code-wise**, but implication is to disable adding links for attachments, which looks nicer but breaks compatibility with old GNU/Social servers. ### `nsfwCensorImage` Use custom image for NSFW'd images diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md new file mode 100644 index 00000000..fb750a66 --- /dev/null +++ b/docs/USER_GUIDE.md @@ -0,0 +1,67 @@ +> Be prepared for breaking changes, unexpected behavior and this user guide becoming obsolete and wrong. + +> If there was no insanity +> it would be necessary to create it. +> --Catbag + +# Pleroma-FE user guide + +Pleroma-FE user interface is modeled after Qvitter which is modeled after older Twitter design. It provides a simple 2-column interface for microblogging. While being simple by default it also provides many powerful customization options. + +## Posting, reading, basic functions. + +After registering and logging in you're presented with your timeline in right column and new post form with timeline list and notifications in the left column. + +When posting links will automatically become hyperlinks, @user@instnace.tld and @user like text will become mentions with link, #tag like text will become link to a tag. Mentioning someone will notify that user that you've mentioned them, there's no way around that except for not using @ in the beginning or referring to them in some other way. + +**Depending on your instance some of the options might not be available or have different defaults** + +Let's clear up some basic stuff. When you post something it's called a **post** or it could be called a **status** or even a **toot** or a **prööt** depending on whom you ask. Post has body/content but it also has some other stuff in it - from attachments, visibility scope, subject line. +* **Attachments** are fairly simple - you can attach any file to a post as long as the file is within maximum size limits. If you're uploading explicit material you can mark all of your attachments as sensitive (or add `#nsfw` tag) - it will hide the images and videos behind a warning so that it won't be displayed instantly. +* **Subject line** also known as **CW** (Content Warning) could be used as a header to the post and/or to warn others about contents of the post having something that might upset somebody or something among those lines. Several applications allow to hide post content leaving only subject line visible. As a side-effect using subject line will also mark your images as sensitive (see above). +* **Visiblity scope** this one is a bit complicated. Normally all posts are `public` (and this is the *only* option on some software like GNU/Social) but if you want it, you can make it your post `unlisted` which will prevent it from showing up on *Public Timeline* and *TWKN* but AFAIK it doesn't prevent it from showing up in search. `Followers only` (sometimes referred as `fo`) posts are only visible to **your** followers, it's implied to be used in conjunction with [locking your account down to only approved followers](#user-settings) since otherwise it doesn't provide much protection since anyone would be able to follow you and read the fo posts. Another problem with fo posts is that each post is visible to followers of the user posted, so if two users are having a conversations with followers only posts you'll probably see only one side of the conversation. `Direct` posts are direct "messages", they are just regular posts but visible only to people who are mentioned in the post, so be very careful when using direct messages since if you want to mention someone else they will also receive your message, but they won't receive all previous ones. Another note of advice - direct messages could potentially be read by instance admins and attachments in DMs are visible to anyone who has a link to the attachment, so using direct messages as a *secure* method of communication is ill-advised. +* **Reply-to** if you are replying to someone, your post will also contain a note that your post is referring to the post you're replying to. Person you're replying to will receive a notification *even* if you remove them from mentioned people. You won't receive notifications when replying to your own posts, but it's useful to reply to your own posts to provide people some context if it's a follow-up to a previous post. There's a small "Reply to ..." label under post author's name which you can hover on to see what post it's referring to. + +Another note: PleromaFE provides a simplified way of posting, however there a lot of stuff going on inside and some other applications allow you to tweak the inmost details of a post - for example you can set "to" and "cc" fields without actually mentioning people, so if you see a post in your notifications that's supposedly not replying to you and doesn't have you in the mentions - it's probably one of those. + +#### Rich text + +By default new posts you make are plaintext, meaning you can't make text **bold** or add custom links or make lists or anything like that. However if your instance allows it you can use Markdown or BBCode or HTML to spice up your text, however there are certain limitations to what HTML tags and what features of Markdown you can use. + +this section will be expanded later + +### Other actions + +In addition to posting you can also *favorite* post also known as *liking* them and *repeat* posts (also known as *retweeting*, *boosting* and even *reprööting*). Favoriting a post increments a counter on it, notifies post author of your affection towards that post and also adds that post to your "favorited" posts list (in your own profile, "Favorites" tab). Reprööting a post does all that and also repeats this post to your followers and your profile page with a note "*user* repeated post". + +You can also delete your own posts (and posts of other people if you're a moderator, but it's slightly different as it won't delete posts by people on other instances) however it's not entirely reliable since deleting a post basically sends a notification "please delete this post" and it may or may not reach all instances, as well as client applications may or may not receive deletion notification from server so post will remain until entire data is refreshed. + +There's also an option to report a user via a post (if the feature is available on your instance) which could be used to notify your (and probably other instance's) admin that someone is being naughty. + +## Users + +When you see someone, you can click on their user picture to view their profile, and click on the userpic in that to see *full* profile. You can *follow* them, *mute* and *block* them. Following is self-explanatory, it adds them t your Home Timeline, lists you as a follower and gives you access to follower-only posts if they have any. Muting makes posts and notifications made by them very tiny, giving you an option to see the post if you're curious. However on clients other than PleromaFE their posts will be completely removed. *Blocking* a user removes them from your timeline and notifications and prevents them from following you (automatically unfollows them from you). + +Please note that some users can be "locked", meaning instead of following them you send a follow request they need to approve for you to become their follower. + +## Timelines + +Currently you have several timelines to browse trough: +* **Timeline** aka Home Timeline - this timeline contains all posts by people you follow and your own posts +* **Interactions** all interactions you've had with people on the network, basically same as notifications except grouped in convenient way - mentions separate from favorites with repeats separate from follows +* **Direct Messages** all posts with `direct` scope addressed to you or mentioning you. +* **Public Timelines** all posts made by users on instance you're on +* **The Whole Known Network** also known as **TWKN** or **Federated Timeline** - all posts on the network by everyone, almost. Due to nature of the network your instance may not know *all** the instances on the network, so only posts originating from known instances are shown there. + +## Other stuff + +By default you can see **ALL** posts made by other users on your Home Timeline, this contrast behavior of Twitter and Mastodon, which shows you only non-reply posts and replies to people you follow. You can set it up to replicate the said behavior, however the option is currently broken. + +You can view other people's profiles and search for users (top-right corner, person with a plus icon). Tag search is possible but not implemented properly yet, right now you can click on tag link in a post to see posts tagged with that post. + +You can also view posts you've favorited on your own profile, but you cannot see favorites by other people. + +Due to nature of how Pleroma (backend) operates you might see old posts appear as if they are new, this is because instance just learned about that post (i.e. your instance is younger that some other ones) and someone interacted with old post. Posts are sorted by date of when they are received, not date they have been posted because it's very easy to spoof the date, so a post claiming it "was" made in year 2077 could hand at top of your TL forever. + +# Customization and configuration +TODO -- cgit v1.2.3-70-g09d2 From 886b097a671c23651550ef52af1f458699534cac Mon Sep 17 00:00:00 2001 From: HJ <30-hj@users.noreply.git.pleroma.social> Date: Mon, 17 Jun 2019 16:06:01 +0000 Subject: Apply suggestion to docs/CONFIGURATION.md --- docs/CONFIGURATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/CONFIGURATION.md') diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index bebf8c3b..1b14b9ab 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -48,7 +48,7 @@ Copy post scope (visibility) when replying to a post. Instance-default. ### `subjectLineBehavior` How to handle subject line (CW) when replying to a post. * `"email"` - like EMail - prepend `re: ` to subject line if it doesn't already start with it. -* `"masto"` - lime Mastodon - copy it as is. +* `"masto"` - like Mastodon - copy it as is. * `"noop"` - do not copy Instance-default. -- cgit v1.2.3-70-g09d2 From 3ec9ef89756e994cd8e1611cf674746574a696ae Mon Sep 17 00:00:00 2001 From: HJ <30-hj@users.noreply.git.pleroma.social> Date: Mon, 17 Jun 2019 16:08:32 +0000 Subject: Apply suggestion to docs/CONFIGURATION.md --- docs/CONFIGURATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/CONFIGURATION.md') diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 1b14b9ab..b78234c6 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -7,7 +7,7 @@ PleromaFE gets its configuration from several sources, in order of preference (the one above overrides ones below it) -1. `/api/statusnet/config.json` - this is generated on Backend and contains multiple things including instance name, char limit etc. It also contains FE/Client-specific data, PleromaFE uses `pleromafe` field of it. For more info on changing config on BE, look [here](https://git.pleroma.social/pleroma/pleroma/blob/develop/docs/config.md#frontend_configurations) +1. `/api/statusnet/config.json` - this is generated on Backend and contains multiple things including instance name, char limit etc. It also contains FE/Client-specific data, PleromaFE uses `pleromafe` field of it. For more info on changing config on BE, look [here](https://docs-develop.pleroma.social/config.html#frontend_configurations) 2. `/static/config.json` - this is a static FE-provided file, containing only FE specific configuration. This file is completely optional and could be removed but is useful as a fallback if some configuration JSON property isn't present in BE-provided config. It's also a reference point to check what default configuration are and what JSON properties even exist. In local dev mode it could be used to override BE configuration, more about that in HACKING.md. File is located [here](https://git.pleroma.social/pleroma/pleroma-fe/blob/develop/static/config.json). 3. Built-in defaults. Those are hard-coded defaults that are used when `/static/config.json` is not available and BE-provided configuration JSON is missing some JSON properties. ( [Code](https://git.pleroma.social/pleroma/pleroma-fe/blob/develop/src/modules/instance.js) ) -- cgit v1.2.3-70-g09d2 From 27b898f5c97758e10884ee6234c74b67f288a125 Mon Sep 17 00:00:00 2001 From: Henry Jameson Date: Wed, 26 Jun 2019 23:44:05 +0300 Subject: More configuration --- docs/CONFIGURATION.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) (limited to 'docs/CONFIGURATION.md') diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index b78234c6..7011f56a 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -34,7 +34,7 @@ Instance `logo`, could be any image, including svg. By default it assumes logo u These two settings should point to where FE should redirect visitor when they login/open up website root ### `chatDisabled` -unused (?) +hides the chat (TODO: even if it's enabled on backend) ### `showInstanceSpecificPanel` This allows you to include arbitrary HTML content in a panel below navigation menu. PleromaFE looks for an html page `instance/panel.html`, by default it's not provided in FE, but BE bundles some [default one](https://git.pleroma.social/pleroma/pleroma/blob/develop/priv/static/instance/panel.html). De-facto instance-defaults, since user can hide instance-specific panel. @@ -59,7 +59,7 @@ Default post formatting option (markdown/bbcode/plaintext/etc...) `true` - will always show subject line input, `false` - only show when it's not empty (i.e. replying). To hide subject line input completely, set it to `false` and `subjectLineBehavior` to `"noop"` ### `hidePostStats` and `hideUserStats` -Hide counters for posts and users respectively, i.e. hiding repeats/favorites counts for posts, hiding followers/friends counts for users. +Hide counters for posts and users respectively, i.e. hiding repeats/favorites counts for posts, hiding followers/friends counts for users. This is just cosmetic and aimed to ease pressure and bias imposed by stat numbers of people and/or posts. (as an example: so that people care less about how many followers someone has since they can't see that info) ### `loginMethod` `"password"` - show simple password field @@ -76,3 +76,18 @@ Use custom image for NSFW'd images ### `showFeaturesPanel` Show panel showcasing instance features/settings to logged-out visitors + +## Indirect configuration +Some features are configured depending on how backend is configured. In general the approach is "if backend allows it there's no need to hide it, if backend doesn't allow it there's no need to show it**. + +### Chat +**TODO somewhat broken, see: chatDisabled** chat can be disabled by disabling it in backend + +### Rich text formatting in post formatting +Rich text formatting options are displayed depending on how many formatting options are enabled on backend, if you don't want your users to use rich text at all you can only allow "text/plain" one, frontend then will only display post text format as a label instead of dropdown (just so that users know for example if you only allow Markdown, only BBCode or only Plain text) + +### Who to follow +This is a panel intended for users to find people to follow based on randomness or on post contents. Being potentially privacy unfriendly feature it needs to be enabled and configured in backend to be enabled. + +### "Safe" DMs +There's obscure option to enable quote-unquote "safe" DMs, which makes DMs "only be visible to the mentioned users at the beginning of the message." which only changes DM warning in FE. What it does precisely is unclear and should probably be avoided since it bring in more confusion and doesn't affect other servers. -- cgit v1.2.3-70-g09d2 From 277553094b123b726758ced2674a3c83fc8cb771 Mon Sep 17 00:00:00 2001 From: Henry Jameson Date: Thu, 27 Jun 2019 00:16:42 +0300 Subject: formatting fix --- docs/CONFIGURATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/CONFIGURATION.md') diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 7011f56a..b603f55a 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -78,7 +78,7 @@ Use custom image for NSFW'd images Show panel showcasing instance features/settings to logged-out visitors ## Indirect configuration -Some features are configured depending on how backend is configured. In general the approach is "if backend allows it there's no need to hide it, if backend doesn't allow it there's no need to show it**. +Some features are configured depending on how backend is configured. In general the approach is "if backend allows it there's no need to hide it, if backend doesn't allow it there's no need to show it. ### Chat **TODO somewhat broken, see: chatDisabled** chat can be disabled by disabling it in backend -- cgit v1.2.3-70-g09d2 From 225090bb79553ba3994e1a68276018d9eaa872f7 Mon Sep 17 00:00:00 2001 From: HJ <30-hj@users.noreply.git.pleroma.social> Date: Fri, 28 Jun 2019 12:29:44 +0000 Subject: Apply suggestion to docs/CONFIGURATION.md --- docs/CONFIGURATION.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'docs/CONFIGURATION.md') diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index b603f55a..a7dcd915 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -89,5 +89,10 @@ Rich text formatting options are displayed depending on how many formatting opti ### Who to follow This is a panel intended for users to find people to follow based on randomness or on post contents. Being potentially privacy unfriendly feature it needs to be enabled and configured in backend to be enabled. -### "Safe" DMs -There's obscure option to enable quote-unquote "safe" DMs, which makes DMs "only be visible to the mentioned users at the beginning of the message." which only changes DM warning in FE. What it does precisely is unclear and should probably be avoided since it bring in more confusion and doesn't affect other servers. +### Safe DM message display + +Setting this will change the warning text that is displayed for direct messages. + +ATTENTION: If you actually want the behavior to change. You will need to set the appropriate option at the backend. See the backend documentation for information about that. + +DO NOT activate this without checking the backend configuration first! -- cgit v1.2.3-70-g09d2