commit eeca1988ce299da314f721f5031a92b8b9157ca0
parent efbc5dab6a041e81fbf4c4eccbae43a7a9997566
Author: f0x52 <f0x@cthu.lu>
Date: Mon, 13 Feb 2023 12:40:24 +0100
[docs] Update user/admin settings docs (#1491)
* update user/admin settings docs
* trigger read-the-docs pr hook
* update menu links
* update images
Diffstat:
15 files changed, 185 insertions(+), 145 deletions(-)
diff --git a/docs/admin/admin_panel.md b/docs/admin/admin_panel.md
@@ -1,26 +0,0 @@
-# Admin Control Panel
-
-The GoToSocial admin panel is a simple webclient that uses the [admin api routes](https://docs.gotosocial.org/en/latest/api/swagger/#operations-tag-admin) to manage your instance. It uses the same OAUTH mechanism as normal clients (with scope: admin), and as such can be hosted anywhere, separately from your instance, or run locally. A public installation is available here: [https://gts.superseriousbusiness.org/admin](https://gts.superseriousbusiness.org/admin).
-
-## Using the panel
-To use the Admin API your account has to be promoted as such:
-```
-./gotosocial --config-path ./config.yaml admin account promote --username YOUR_USERNAME
-```
-After this, you can enter your instance domain in the login field (auto-filled if you run GoToSocial on the same domain), and login like you would with
-any other client.
-
-<p align="middle">
- <img src="../../assets/admin-panel.png">Screenshot of the GoToSocial admin panel, showing the fields to change an instance's settings</img>
-</p>
-
-You can change the instance's settings like the title and descriptions, and add/remove/change domain blocks including a bulk import/export.
-
-## Building the panel
-Build requirements: some version of [Node.js](https://nodejs.org) and yarn.
-```
-yarn install --cwd web/source
-BUDO_BUILD=1 node web/source
-```
-
-See also: [Contributing.md Stylesheet / Web dev](https://github.com/superseriousbusiness/gotosocial/blob/main/CONTRIBUTING.md#stylesheet--web-dev)
-\ No newline at end of file
diff --git a/docs/admin/settings.md b/docs/admin/settings.md
@@ -0,0 +1,57 @@
+# Admin Settings
+
+The GoToSocial Settings interface uses the [admin api routes](https://docs.gotosocial.org/en/latest/api/swagger/#operations-tag-admin) to manage your instance. It's combined with the [User settings](../user_guide/settings.md) and uses the same OAUTH mechanism as normal clients (with scope: admin).
+
+## Account permissions
+To use the Admin API your account has to be promoted as such:
+```
+./gotosocial --config-path ./config.yaml admin account promote --username YOUR_USERNAME
+```
+
+After this, you can enter your instance domain in the login field (auto-filled if you run GoToSocial on the same domain), and login like you would with any other client.
+
+
+## Instance Settings
+
+
+Here you can set various metadata for your instance, like the displayed name, thumbnail image, description texts (HTML), and contact username and email.
+
+## Actions
+You can use media cleanup to remove remote media older than the specified number of days. This also removes unused headers and avatars.
+
+## Federation
+
+
+In the federation section you can influence which instances you federate with, through adding domain blocks. You can enter a domain to suspend in the search field, which will filter the list to show you if you already have a block for it. Clicking 'suspend' gives you a form to add a public and/or private comment, and submit to add the block. Adding a suspension will suspend all the currently known accounts on the instance, and prevent any new interactions with any user on the blocked instance.
+
+### Bulk import/export
+Through the link at the bottom of the Federation section (or going to `/settings/admin/federation/import-export`) you can do bulk import/export of your domain blocklist.
+
+
+
+Upon importing a list, either through the input field or from a file, you can review the entries in the list before importing a subset. You'll also be warned for entries that use subdomains, providing an easy way to change them to the main domain.
+
+## Reports
+
+
+The reports section shows a list of reports, originating from your local users, or remote instances (shown anonymously as just the name of the instance, without specific username).
+
+Clicking a report shows if it was resolved (with the reasoning if available), more information, and a list of reported toots if selected by the reporting user.
+
+## Custom Emoji
+Custom Emoji will be automatically fetched when included in remote toots, but to use them in your own posts they have to be enabled on your instance.
+
+### Local
+
+
+This section shows an overview of all the custom emoji enabled on your instance, sorted by their category. Clicking an emoji shows it's details, and provides options to change the category or image, or delete it completely. The shortcode cannot be updated here, you would have to upload it with the new shortcode yourself (and optionally delete the old one).
+
+Below the overview you can upload your own custom emoji, after previewing how they look in a toot. PNG and (animated) GIF's are supported.
+
+### Remote
+
+
+Through the 'remote' section, you can look up a link to any remote toots (provided the instance isn't suspended). If they use any custom emoji they will be listed, providing an easy way to copy them to the local emoji (for use in your own toots), or disable them ( hiding them from toots).
+
+**Note:** as the testrig server does not federate, this feature can't be used in development (500: Internal Server Error).
+
diff --git a/docs/assets/admin-panel.png b/docs/assets/admin-panel.png
Binary files differ.
diff --git a/docs/assets/admin-settings-emoji-local.png b/docs/assets/admin-settings-emoji-local.png
Binary files differ.
diff --git a/docs/assets/admin-settings-emoji-remote.png b/docs/assets/admin-settings-emoji-remote.png
Binary files differ.
diff --git a/docs/assets/admin-settings-federation-import-export.png b/docs/assets/admin-settings-federation-import-export.png
Binary files differ.
diff --git a/docs/assets/admin-settings-federation.png b/docs/assets/admin-settings-federation.png
Binary files differ.
diff --git a/docs/assets/admin-settings-reports.png b/docs/assets/admin-settings-reports.png
Binary files differ.
diff --git a/docs/assets/admin-settings.png b/docs/assets/admin-settings.png
Binary files differ.
diff --git a/docs/assets/user-settings-password-change.png b/docs/assets/user-settings-password-change.png
Binary files differ.
diff --git a/docs/assets/user-settings-post-settings.png b/docs/assets/user-settings-post-settings.png
Binary files differ.
diff --git a/docs/assets/user-settings-profile-info.png b/docs/assets/user-settings-profile-info.png
Binary files differ.
diff --git a/docs/user_guide/settings.md b/docs/user_guide/settings.md
@@ -0,0 +1,84 @@
+# Settings
+
+GoToSocial provides a settings interface where you can update your post settings, add an avatar and header image, write a bio for your account, and so on.
+
+You can access the Settings at `https://my-instance.example.com/settings` with your own GoToSocial instance. It uses the same OAUTH mechanism as normal clients (with scope: admin), and as such can be accessed from anywhere, separately from your own instance, or ran locally. A public installation is available here: [https://gts.superseriousbusiness.org/settings](https://gts.superseriousbusiness.org).
+
+You will be prompted to log in with your email address and password after providing the instance url (auto-filled when using the page that comes with your instance).
+
+## Profile
+
+
+
+In the profile section you can change your display name, avatar and header images. You can also choose to enable manually approving follow requests, and opt-in to providing a public RSS feed of your posts.
+
+### Set Avatar / Header
+
+To set an avatar or header image, click on the `Browse` button in the appropriate section, and use the file browser to select an image.
+
+Currently, supported image formats are `gif`, `png`, and `jpeg`/`jpg`.
+
+A preview of the image as it will appear on your profile will be shown. If you're happy with your choices, click on the `Save profile info` button at the bottom of the Profile Info section. If you navigate to your profile and refresh the page, your new avatar / header will be shown. It might take a bit longer for the update to federate out to remote instances.
+
+### Set Displayname and Bio
+
+Your display name is a short handle shown alongside your username on your profile. While your username cannot be changed once it's created, your display name can. Your display name can also contain spaces, capital letters, emojis, and so on. It's a great place to put a nickname, full name, and/or pronouns. For example, if your username is `@miranda`, your display name could be something like `Miranda Priestly (she/her)`.
+
+Your bio is a longer text that introduces your account and your self. Your bio is a good place to:
+
+- Give an indication of the sort of things you post about
+- Mention your approximate age / location
+- Link to any of your other accounts or profiles elsewhere
+- Describe your boundaries and preferences when it comes to other people interacting with you
+- Link hashtags that you often use when you post
+
+The bio accepts either `plain` or `markdown` formatting. This is set by the default post format setting described in [User Settings](#user-settings).
+
+After updating your display name and bio, click on the `Save profile info` button at the bottom of the Profile Info section to save your changes.
+
+### Manually Approve Followe Requests / Lock Your Account
+
+At the bottom of the Profile Info section, there's a checkbox to manually approve follow requests.
+
+When this is **not checked**, new follow requests are approved automatically without your intervention. This is useful for more public-facing accounts or cases where you don't really post anything sensitive or private.
+
+When it is **checked**, you must manually approve new follow requests, and you can deny follow requests from accounts you don't want to follow you. This is useful for private accounts where you post personal things to followers only.
+
+This option is often referred to on the fediverse as "locking" your account.
+
+After ticking or unticking the checkbox, be sure to click on the `Save profile info` button at the bottom to save your new settings.
+
+### Enable RSS feed of Public posts
+
+RSS (Really Simple Syndication) is a protocol for web feeds separate from ActivityPub, where users can aggregrate various feeds from different sites like blogs and podcasts. It's important to note that this by-passes follow requests, allowing anyone to get updates on your public posts. This feed only includes posts set as 'Public' (see [Privacy Settings](./posts.md#privacy-settings)).
+
+### Custom CSS
+If enabled on your instance, [Custom CSS](./custom_css.md) allows you to theme the way your profile looks when visited through a browser. When this setting is not enabled, the field is hidden.
+
+## Settings
+
+
+
+In the 'Settings' section, you can set various defaults for new posts.
+
+The default post language setting allows you to indicate to other fediverse users which language your posts are usually written in. This is helpful for fediverse users who speak (for example) Korean, and would prefer to filter out posts written in other languages.
+
+The default post privacy setting allows you to set the default privacy for new posts. This is useful when you generally prefer to post public or followers-only, but you don't want to have to remember to set the privacy every time you post. Remember, this is only the default: no matter what you set here, you can still set the privacy individually for new posts if desired. For more information on post privacy settings, see the [page on Posts](./posts.md).
+
+The default post format setting allows you to set which text interpreter should be used when parsing your posts.
+
+The plain (default) setting provides standard post formatting, similar to what many other fediverse servers use. This is great for general purpose posting: you can write short, twitter-style posts, or multi-paragraph essays, insert links, and mention other accounts using their username.
+
+The markdown setting indicates that your posts should be parsed as Markdown, which is a markup language that gives you more options for customizing the layout and appearance of your posts. For more information on the differences between plain and markdown post formats, see the [posts page](posts.md).
+
+When you are finished updating your post settings, remember to click the `Save post settings` button at the bottom of the section to save your changes.
+
+## Password Change
+
+You can use the Password Change section of the User Settings Panel to set a new password for your account.
+
+For more information on the way GoToSocial manages passwords, please see the [Password management document](./password_management.md).
+
+## Admins
+
+If your account has been promoted to admin, this interface will also show sections related to admin actions, see [Admin Settings](../admin/settings.md).
+\ No newline at end of file
diff --git a/docs/user_guide/user_panel.md b/docs/user_guide/user_panel.md
@@ -1,75 +0,0 @@
-# User Settings Panel
-
-GoToSocial provides a settings panel where you can update your post settings, add an avatar and header image, write a bio for your account, and so on.
-
-You can access the User Settings Panel at `/user` on your instance. If your instance is at `https://www.example.org`, then your User Settings Panel will be at `https://www.example.org/user`.
-
-You will be prompted to log in to the User Settings Panel with your email address and password.
-
-## Profile Info
-
-
-
-In the first section of the User Settings Panel, you can upload header and avatar images for your profile, update your display name and bio, and toggle whether or not to manually approve new follow requests.
-
-### Set Avatar / Header
-
-To set an avatar or header image, click on the `Browse` button in the appropriate section, and use the file browser to select an image.
-
-Currently, supported image formats are `gif`, `png`, and `jpeg`/`jpg`.
-
-A preview of the image as it will appear on your profile will be shown. If you're happy with your choices, click on the `Save profile info` button at the bottom of the Profile Info section. If you navigate to your profile in the web browser and refresh the page, your new avatar / header will be shown.
-
-### Set Display Name and Bio
-
-Your display name is a short handle shown alongside your username on your profile. While your username cannot be changed once it's created, your display name can. Your display name can also contain spaces, capital letters, emojis, and so on. It's a great place to put a nickname, full name, and/or pronouns. For example, if your username is `@miranda`, your display name could be something like `Miranda Priestly (she/her)`.
-
-Your bio is a longer text that introduces your account and your self. Your bio is a good place to:
-
-- Give an indication of the sort of things you post about
-- Mention your approximate age / location
-- Link to any of your other accounts or profiles elsewhere
-- Describe your boundaries and preferences when it comes to other people interacting with you
-- Link hashtags that you often use when you post
-
-The bio accepts either `plain` or `markdown` formatting. This is set by the default post format setting described in [Post Settings](#post-settings).
-
-After updating your display name and bio, click on the `Save profile info` button at the bottom of the Profile Info section to save your changes.
-
-### Manually Approve Followers / Lock Your Account
-
-At the bottom of the Profile Info section, there's a checkbox to manually approve follow requests.
-
-When this is **not checked**, new follow requests are approved automatically without your intervention. This is useful for more public-facing accounts or cases where you don't really post anything sensitive or private.
-
-When it is **checked**, you must manually approve new follow requests, and you can deny follow requests from accounts you don't want to follow you. This is useful for private accounts where you post personal things to followers only.
-
-This option is often referred to on the fediverse as "locking" your account.
-
-After ticking or unticking the checkbox, be sure to click on the `Save profile info` button at the bottom to save your new settings.
-
-## Post Settings
-
-
-
-In the Post Settings section of the User Settings Panel, you can set various defaults for new posts.
-
-The default post language setting allows you to indicate to other fediverse users which language your posts are usually written in. This is helpful for fediverse users who speak (for example) Korean, and would prefer to filter out posts written in other languages.
-
-The default post privacy setting allows you to set the default privacy for new posts. This is useful when you generally prefer to post public or followers-only, but you don't want to have to remember to set the privacy every time you post. Remember, this is only the default: no matter what you set here, you can still set the privacy individually for new posts if desired. For more information on post privacy settings, see the [posts page](./posts.md).
-
-The default post format setting allows you to set which text interpreter should be used when parsing your posts.
-
-The plain (default) setting provides standard post formatting, similar to what many other fediverse servers use. This is great for general purpose posting: you can write short, twitter-style posts, or multi-paragraph essays, insert links, and mention other accounts using their username.
-
-The markdown setting indicates that your posts should be parsed as Markdown, which is a markup language that gives you more options for customizing the layout and appearance of your posts. For more information on the differences between plain and markdown post formats, see the [posts page](posts.md).
-
-When you are finished updating your post settings, remember to click the `Save post settings` button at the bottom of the section to save your changes.
-
-## Password Change
-
-
-
-You can use the Password Change section of the User Settings Panel to set a new password for your account.
-
-For more information on GoToSocial password managing, please see the [password management document](./password_management.md).
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -19,51 +19,51 @@ nav:
- "Home": "index.md"
- "FAQ": "faq.md"
- "User Guide":
- - "user_guide/posts.md"
- - "user_guide/user_panel.md"
- - "user_guide/custom_css.md"
- - "user_guide/password_management.md"
- - "user_guide/rss.md"
+ - "user_guide/posts.md"
+ - "user_guide/settings.md"
+ - "user_guide/custom_css.md"
+ - "user_guide/password_management.md"
+ - "user_guide/rss.md"
- "Installation Guide":
- - "installation_guide/index.md"
- - "installation_guide/binary.md"
- - "installation_guide/docker.md"
- - "installation_guide/nginx.md"
- - "installation_guide/apache-httpd.md"
- - "installation_guide/caddy.md"
- - "installation_guide/third_party.md"
- - "installation_guide/websocket.md"
- - "installation_guide/advanced.md"
+ - "installation_guide/index.md"
+ - "installation_guide/binary.md"
+ - "installation_guide/docker.md"
+ - "installation_guide/nginx.md"
+ - "installation_guide/apache-httpd.md"
+ - "installation_guide/caddy.md"
+ - "installation_guide/third_party.md"
+ - "installation_guide/websocket.md"
+ - "installation_guide/advanced.md"
- "Configuration":
- - "configuration/index.md"
- - "configuration/general.md"
- - "configuration/database.md"
- - "configuration/web.md"
- - "configuration/instance.md"
- - "configuration/accounts.md"
- - "configuration/media.md"
- - "configuration/storage.md"
- - "configuration/statuses.md"
- - "configuration/letsencrypt.md"
- - "configuration/oidc.md"
- - "configuration/smtp.md"
- - "configuration/syslog.md"
- - "configuration/advanced.md"
+ - "configuration/index.md"
+ - "configuration/general.md"
+ - "configuration/database.md"
+ - "configuration/web.md"
+ - "configuration/instance.md"
+ - "configuration/accounts.md"
+ - "configuration/media.md"
+ - "configuration/storage.md"
+ - "configuration/statuses.md"
+ - "configuration/letsencrypt.md"
+ - "configuration/oidc.md"
+ - "configuration/smtp.md"
+ - "configuration/syslog.md"
+ - "configuration/advanced.md"
- "Admin":
- - "admin/admin_panel.md"
- - "admin/cli.md"
- - "admin/backup_and_restore.md"
+ - "admin/settings.md"
+ - "admin/cli.md"
+ - "admin/backup_and_restore.md"
- "Federation":
- - "federation/index.md"
- - "federation/glossary.md"
- - "Federating With GoToSocial":
- - "federation/federating_with_gotosocial/http_signatures.md"
- - "federation/federating_with_gotosocial/access_control.md"
- - "federation/federating_with_gotosocial/request_throttling.md"
- - "federation/federating_with_gotosocial/outbox.md"
- - "federation/federating_with_gotosocial/conversation_threads.md"
- - "federation/federating_with_gotosocial/reports.md"
+ - "federation/index.md"
+ - "federation/glossary.md"
+ - "Federating With GoToSocial":
+ - "federation/federating_with_gotosocial/http_signatures.md"
+ - "federation/federating_with_gotosocial/access_control.md"
+ - "federation/federating_with_gotosocial/request_throttling.md"
+ - "federation/federating_with_gotosocial/outbox.md"
+ - "federation/federating_with_gotosocial/conversation_threads.md"
+ - "federation/federating_with_gotosocial/reports.md"
- "API Documentation":
- - "api/swagger.md"
- - "api/ratelimiting.md"
- - "api/throttling.md"
+ - "api/swagger.md"
+ - "api/ratelimiting.md"
+ - "api/throttling.md"
