diff --git a/.gitignore b/.gitignore index c8beda86..a400ce86 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,4 @@ selenium-debug.log .idea/ config/local.json config/local.*.json +docs/site/ diff --git a/docs/docs/stickers.md b/docs/docs/stickers.md new file mode 100644 index 00000000..ac4a1eca --- /dev/null +++ b/docs/docs/stickers.md @@ -0,0 +1,53 @@ +# Adding stickers + +Pleroma-fe supports stickers, which are essentially little images stored server-side +which can be selected by a user to automatically attach them to a post. + +There's no explicit setting for these, they just rely on the existence of certain files. + +## Initialising the sticker config file + +You're probably serving pleroma-fe from your instance's `instance/static/` directory - +this directy can also override files served at a given path. + +The first thing we need to do is set up our `stickers.json` file. At `instance/static/static/stickers.json`, +put a file that looks like this + +```json +{ + "myPack": "/static/stickers/myPack" +} +``` + +This file is a mapping from name to pack directory location. It says "we have a pack called myPack, look for +it at `/static/stickers/myPack`". You can add as many packs as you like in this manner. + +## Creating the pack + +First, create your pack directory + +```bash +mkdir -p instance/static/static/stickers/myPack +``` + +Now you need to give it some config. + +At `instance/static/static/stickers/myPack/pack.json`, put a file that looks like: + +```json +{ + "title": "myPack", + "author": "me for i am very cool", + "tabIcon": "tab.png", + "stickers": [ + "mySticker.png" + ] +} +``` + +This should be relatively self-explanatory, it declares a pack with a title `myPack` which has only one sticker in it. +The `tabIcon` will appear on the sticker picker itself as a representative of the pack. + +You can add as many stickers as you like. They should all be in the same directory as your `pack.json`. + +Now you should find that there's a sticky note icon on the emoji picker on pleroma-fe that allows you to attach stickers. diff --git a/docs/site/404.html b/docs/site/404.html deleted file mode 100644 index 72b37321..00000000 --- a/docs/site/404.html +++ /dev/null @@ -1,479 +0,0 @@ - - - -
- - - - - - - - - - - -PleromaFE gets its configuration from several sources, in order of preference (the one above overrides ones below it)
-/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/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./static/config.json
is not available and BE-provided configuration JSON is missing some JSON properties. ( Code )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.
-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"
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.
collapseMessageWithSubject
¶Collapse post content when post has a subject line (content warning). Instance-default.
-disableChat
¶hides the chat (TODO: even if it's enabled on backend)
-greentext
¶Changes lines prefixed with the >
character to have a green text color
hideFilteredStatuses
¶Removes filtered statuses from timelines.
-hideMutedPosts
¶Removes muted statuses from timelines.
-hidePostStats
¶Hide repeats/favorites counters for posts.
-hideSitename
¶Hide instance name in header.
-hideUserStats
¶Hide followers/friends counters for users.
-loginMethod
¶"password"
- show simple password field
-"token"
- show button to log in with external method (will redirect to login form, more details in BE documentation)
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. 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.
minimalScopesMode
¶Limit scope selection to Direct, User default and Scope of post replying to. This also makes it impossible to reply to a DM with a non-DM post from PleromaFE.
-nsfwCensorImage
¶Use custom image for NSFW'd images
-postContentType
¶Default post formatting option (markdown/bbcode/plaintext/etc...)
-redirectRootNoLogin
, redirectRootLogin
¶These two settings should point to where FE should redirect visitor when they login/open up website root
-scopeCopy
¶Copy post scope (visibility) when replying to a post. Instance-default.
-sidebarRight
¶Change alignment of sidebar and panels to the right. Defaults to false
.
showFeaturesPanel
¶Show panel showcasing instance features/settings to logged-out visitors
-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. De-facto instance-defaults, since user can hide instance-specific panel.
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"
- like Mastodon - copy it as is.
-* "noop"
- do not copy
-Instance-default.
theme
¶Default theme used for new users. De-facto instance-default, user can change theme.
-webPushNotifications
¶Enables PushAPI - based notifications for users. Instance-default.
-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.
-TODO somewhat broken, see: disableChat chat can be disabled by disabling it in backend
-If the private
instance setting is enabled in the backend, features that are not accessible without authentication, such as the timelines and search will be disabled for unauthenticated users.
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)
-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.
- - -PleromaFE is an SPA (Single-Page Application) backed by Vue framework. It means that it's just a nearly-empty HTML page with bunch of JavaScript that actually generates and controls DOM (i.e. html elements) in Runtime. Currently, there's no way around it - you have to have Javascript enabled in the browser to make it work, there is a theoretical possibility to generate some HTML server-side but it's not implemented yet.
-You can serve static html page and everything from any HTTP(S) server but currently it will try to access /api/ path at same domain it's running on, meaning that as of right now you cannot put it on one domain and access the other without proxying requests.
-Development server does exactly that - it serves static html page with javascript and all other assets, adds some code to automatically reload when changes to code are made and proxies requests to some other server.
-Setting up development server is fairly straight-forward.
-cd
into it and run yarn
to fetch dependencies.config/local.example.json
to config/local.json
and change the target
to point at instance you want, otherwise it will point to localhost:4000
which is default address for locally-run Pleroma Backendyarn dev
- it will start the server.localhost:8080
in your browser, it might take a while initially until everything is built first time.This could be a bit trickier, you basically need steps 1-4 from develop build instructions, and run yarn build
which will compile and copy eveything needed for production into dist
folder. As said before, this technically could be used anywhere with some details.
This is the most easiest way to use and test FE build: you just need to copy or symlink contents of dist
folder into backend's static directory, by default it is located in instance/static
, or in /var/lib/pleroma/static
for OTP release installations, create it if it doesn't exist already. Be aware that running yarn build
wipes the contents of dist
folder.
This is highly experimental and only tried once, with no actual simple solution available yet
-You will need an HTTP server that can proxy requests for /api
, /instance
, /nodeinfo
and show index.html for every 404 page.
For nginx you'll probably need something like this:
-server {
- listen 80 default_server;
-
- index index.html index.htm index.nginx-debian.html;
-
- root /var/www/html
-
- location /api {
- proxy_pass https://example.tld;
- }
-
- location /instance {
- proxy_pass https://example.tld;
- }
-
- location /nodeinfo {
- proxy_pass https://example.tld;
- }
-
- location / {
- try_files $uri $uri/ /index.html;
- }
-}
-
(ed. note: this is close to what i used last time i had to do it, it may not work and need additions, i basically adjusted default nginx server in debian)
-In 99% cases PleromaFE uses MastoAPI with Pleroma Extensions to fetch the data. The rest is either QvitterAPI leftovers or pleroma-exclusive APIs. QvitterAPI doesn't exactly have documentation and uses different JSON structure and sometimes different parameters and workflows, this could be a good reference though. Some pleroma-exclusive API may still be using QvitterAPI JSON structure.
-PleromaFE supports both formats by transforming them into internal format which is basically QvitterAPI one with some additions and renaming. All data is passed trough Entity Normalizer which can serve as a reference of API and what's actually used, it's also a host for all the hacks and data transformation.
-For most part, PleromaFE tries to store all the info it can get in global vuex store - every user and post are passed trough updating mechanism where data is either added or merged with existing data, reactively updating the information throughout UI, so if in newest request user's post counter increased, it will be instantly updated in open user profile cards. This is also used to find users, posts and sometimes to build timelines and/or request parameters.
-PleromaFE also tries to persist this store, however only stable data is stored, such as user authentication and preferences, user highlights. Persistence is performed by saving and loading chunk of vuex store in browser's LocalStorage/IndexedDB.
-TODO: Refactor API code and document it here
-PleromaFE uses custom theme "framework" which is pretty much just a style tag rendered by vue which only contains CSS3 variables. Every color used in UI should be derived from theme. Theme is stored in a JSON object containing color, opacity, shadow and font information, with most of it being optional.
-The most basic theme can consist of 4 to 8 "basic colors", which is also what previous version of themes allowed, with all other colors being derived from those basic colors, i.e. "light background" will be "background" color lightened/darkened, "panel header" will be same as "foreground". The idea is that you can specify just basic color palette and everything else will be generated automatically, but if you really need to tweak some specific color - you can.
-As said before - older version only allowed 4 to 8 colors, it also used arrays instead of objects, we still support that. The basic colors are: background, foreground, text, links, red, orange, blue, green. First 4 are mandatory, last 4 have default fallbacks since ever more ancient theme formats only had 4 colors.
-Note that with older version themes used different internal naming when persisting state.
-Themes are meant to be backwards and somewhat forwards compatible - new colors should properly inherit from some existing one, making it compatible with older versions. When loading newer version of theme all unrecognized colors will be ignored, which for most part should be fine, however adding new features (gradients, masks, whatever it might be) might be breaky.
-Lastly, pleroma provides some contrast information and generates readable text color automatically, which is done by tracking background/text color pairs and their contrast - if contrast too low it will try to use background color with inverted lightness, if it's still unacceptable it will fall back to pure black/white.
-Most images are wrapped in a component called StillImage, which does one simple thing - tries to detect if image is a GIF and if it is (and user has enabled relevant setting) it will show <canvas>
with that image instead of actual image. It uses standard method to render an image into canvas which renders first frame of a GIF if it's animated (obviously because canvas by itself isn't animated and you'd need to animate it yourself in JS), it will show actual image on hover. Statuses also allow playing animated avatars when you hover over a post, not just image itself.
Feel free to contribute, most preferred way is by starting a Merge Request in GitLab. Please try to use descriptive names for your branches and merge requests, avoid naming them "fix-issue-777" "777" and so on.
- - -\n {translation(\"search.result.term.missing\")}: {...missing}\n
\n }\n