commit 4c60a142f8386b4c56b76c101baa583b8a18272c
parent e9b5ba0502a85a652bf2e4d8b76007767270c2af
Author: tobi <31960611+tsmethurst@users.noreply.github.com>
Date: Fri, 26 Aug 2022 17:40:54 +0200
[docs] Add user settings panel docs, other small updates (#768)
* add more links to markdown section
* update password management
* add user settings panel documentation
* move the user guide higher up in the docs
Diffstat:
7 files changed, 93 insertions(+), 13 deletions(-)
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/password_management.md b/docs/user_guide/password_management.md
@@ -1,19 +1,19 @@
# Password Management
-GoToSocial stores hashes of user passwords in its database using the secure [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) function in the [Go standard libraries](https://pkg.go.dev/golang.org/x/crypto/bcrypt).
+## Change Your Password
-This means that the plaintext value of your password is safe even if the database of your GoToSocial instance is compromised. It also means that your instance admin does not have access to your password.
+You can use the [User Settings Panel](./user_panel.md) to change your password. Just log in to the user panel, scroll to the bottom of the page, and input your old password and desired new password.
-To check whether a password is sufficiently secure before accepting it, GoToSocial uses [this library](https://github.com/wagslane/go-password-validator) with entropy set to 60. This means that passwords like `password` are rejected, but something like `verylongandsecurepasswordhahaha` would be accepted, even without special characters/upper+lowercase etc.
+If the new password you provide is not long/complicated enough, you will see an error and be prompted to try again with a different password.
-We recommend following the EFF's guidelines on [creating strong passwords](https://ssd.eff.org/en/module/creating-strong-passwords).
+If your instance uses OIDC (ie., you log in via Google or some other external provider), you will have to change your password via your OIDC provider, not through the user settings panel.
-## Change Your Password
+## Password Storage
-### API method
+GoToSocial stores hashes of user passwords in its database using the secure [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) function in the [Go standard libraries](https://pkg.go.dev/golang.org/x/crypto/bcrypt).
-If you are logged in (ie., you have a valid oauth token), you can change your password by making a POST request to `/api/v1/user/password_change`, using your token as authentication, and giving your old password and desired new password as parameters. Check the [API documentation](../api/swagger.md) for more details.
+This means that the plaintext value of your password is safe even if the database of your GoToSocial instance is compromised. It also means that your instance admin does not have access to your password.
-## Reset Your Password
+To check whether a password is sufficiently secure before accepting it, GoToSocial uses [this library](https://github.com/wagslane/go-password-validator) with entropy set to 60. This means that passwords like `password` are rejected, but something like `verylongandsecurepasswordhahaha` would be accepted, even without special characters/upper+lowercase etc.
-todo
+We recommend following the EFF's guidelines on [creating strong passwords](https://ssd.eff.org/en/module/creating-strong-passwords).
diff --git a/docs/user_guide/posts.md b/docs/user_guide/posts.md
@@ -115,7 +115,13 @@ Plain is the default method of posting: GtS accepts some plain looking text, and
Markdown is a more complex way of organizing text, which gives you more control over how your text is parsed and formatted.
-For more information on markdown, see [The Markdown Guide](https://www.markdownguide.org/).
+GoToSocial supports the [Basic Markdown Syntax](https://www.markdownguide.org/basic-syntax), and some of the [Extended Markdown Syntax](https://www.markdownguide.org/extended-syntax/) as well, including fenced code blocks, footnotes, strikethrough, subscript, superscript, and automated URL linking.
+
+You can also include snippets of basic HTML in your markdown!
+
+For more information on Markdown, see [The Markdown Guide](https://www.markdownguide.org/).
+
+For a quick reference on Markdown syntax, see the [Markdown Cheat Sheet](https://www.markdownguide.org/cheat-sheet).
## Formatting
diff --git a/docs/user_guide/user_panel.md b/docs/user_guide/user_panel.md
@@ -0,0 +1,73 @@
+# 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
+
+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
@@ -13,6 +13,10 @@ extra_css:
nav:
- "Home": "index.md"
+ - "User Guide":
+ - "user_guide/posts.md"
+ - "user_guide/user_panel.md"
+ - "user_guide/password_management.md"
- "Installation Guide":
- "installation_guide/index.md"
- "installation_guide/binary.md"
@@ -41,9 +45,6 @@ nav:
- "admin/admin_panel.md"
- "admin/cli.md"
- "admin/backup_and_restore.md"
- - "User Guide":
- - "user_guide/posts.md"
- - "user_guide/password_management.md"
- "Federation":
- "federation/index.md"
- "federation/glossary.md"
