diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/swagger.yaml | 24 | ||||
| -rw-r--r-- | docs/assets/cssblack.png | bin | 0 -> 496562 bytes | |||
| -rw-r--r-- | docs/assets/cssgradient.png | bin | 0 -> 503352 bytes | |||
| -rw-r--r-- | docs/assets/cssstandard.png | bin | 0 -> 499643 bytes | |||
| -rw-r--r-- | docs/configuration/accounts.md | 16 | ||||
| -rw-r--r-- | docs/user_guide/custom_css.md | 73 |
6 files changed, 113 insertions, 0 deletions
diff --git a/docs/api/swagger.yaml b/docs/api/swagger.yaml index ebcf14c02..0d75a6a12 100644 --- a/docs/api/swagger.yaml +++ b/docs/api/swagger.yaml @@ -12,6 +12,17 @@ definitions: title: A FileHeader describes a file part of a multipart request. type: object x-go-package: mime/multipart + InstanceConfigurationAccounts: + properties: + allow_custom_css: + description: Whether or not accounts on this instance are allowed to upload + custom CSS for profiles and statuses. + example: false + type: boolean + x-go-name: AllowCustomCSS + title: InstanceConfigurationAccounts models instance account config parameters. + type: object + x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model Link: description: See https://webfinger.net/ properties: @@ -240,6 +251,11 @@ definitions: example: "2021-07-30T09:20:25+00:00" type: string x-go-name: CreatedAt + custom_css: + description: CustomCSS to include when rendering this account's profile or + statuses. + type: string + x-go-name: CustomCSS discoverable: description: Account has opted into discovery features. type: boolean @@ -1086,6 +1102,8 @@ definitions: x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model instanceConfiguration: properties: + accounts: + $ref: '#/definitions/InstanceConfigurationAccounts' media_attachments: $ref: '#/definitions/instanceConfigurationMediaAttachments' polls: @@ -2618,6 +2636,12 @@ paths: in: formData name: source[status_format] type: string + - description: |- + Custom CSS to use when rendering this account's profile or statuses. + String must be no more than 5,000 characters (~5kb). + in: formData + name: custom_css + type: string produces: - application/json responses: diff --git a/docs/assets/cssblack.png b/docs/assets/cssblack.png Binary files differnew file mode 100644 index 000000000..6c1d91146 --- /dev/null +++ b/docs/assets/cssblack.png diff --git a/docs/assets/cssgradient.png b/docs/assets/cssgradient.png Binary files differnew file mode 100644 index 000000000..23b85dd0e --- /dev/null +++ b/docs/assets/cssgradient.png diff --git a/docs/assets/cssstandard.png b/docs/assets/cssstandard.png Binary files differnew file mode 100644 index 000000000..e4d9cab7c --- /dev/null +++ b/docs/assets/cssstandard.png diff --git a/docs/configuration/accounts.md b/docs/configuration/accounts.md index edb647a1b..3f0c6d5f8 100644 --- a/docs/configuration/accounts.md +++ b/docs/configuration/accounts.md @@ -23,4 +23,20 @@ accounts-approval-required: true # Options: [true, false] # Default: true accounts-reason-required: true + +# Bool. Allow accounts on this instance to set custom CSS for their profile pages and statuses. +# Enabling this setting will allow accounts to upload custom CSS via the /user settings page, +# which will then be rendered on the web view of the account's profile and statuses. +# +# For instances with public sign ups, it is **HIGHLY RECOMMENDED** to leave this setting on 'false', +# since setting it to true allows malicious accounts to make their profile pages misleading, unusable +# or even dangerous to visitors. In other words, you should only enable this setting if you trust +# the users on your instance not to produce harmful CSS. +# +# Regardless of what this value is set to, any uploaded CSS will not be federated to other instances, +# it will only be shown on profiles and statuses on *this* instance. +# +# Options: [true, false] +# Default: false +accounts-allow-custom-css: false ``` diff --git a/docs/user_guide/custom_css.md b/docs/user_guide/custom_css.md new file mode 100644 index 000000000..513074c62 --- /dev/null +++ b/docs/user_guide/custom_css.md @@ -0,0 +1,73 @@ +# Custom CSS (Advanced) + +CSS (Cascading Style Sheets) is a coding language used alongside HTML, which determines how a web page looks in a web browser: + +> While HTML is used to define the structure and semantics of your content, CSS is used to style it and lay it out. For example, you can use CSS to alter the font, color, size, and spacing of your content, split it into multiple columns, or add animations and other decorative features. +> +> -- [Learn CSS (Mozilla)](https://developer.mozilla.org/en-US/docs/Learn/CSS) + +Depending on the settings configured by the admin of your GoToSocial instance, you may be able to upload custom CSS for your account via the User Settings Panel. + +This allows you to customize the appearance of your GoToSocial profile for users visiting it using a web browser. + +## Example - Changing Background Color + +Here's a standard GoToSocial profile page: + + + +Let's say we want the background color to be black instead of grey. + +In the User Settings Panel, we enter the following CSS code in the Custom CSS field: + +```css +.page { + background: black; +} +``` + +We then click on Save Profile Info. + +If we go back to our profile page and refresh the page, it now looks like this: + + + +If we want to get really fancy, we can add an ombre effect to the background, by using the following CSS code instead: + +```css +.page { + background: linear-gradient(crimson, purple); +} +``` + +After saving the css and refreshing the profile page, the profile now looks like this: + + + +## Accessibility + +The importance of accessible HTML and CSS cannot be overstated. From W3: + +> The Web is fundamentally designed to work for all people, whatever their hardware, software, language, location, or ability. When the Web meets this goal, it is accessible to people with a diverse range of hearing, movement, sight, and cognitive ability. +> +> Thus the impact of disability is radically changed on the Web because the Web removes barriers to communication and interaction that many people face in the physical world. However, when websites, applications, technologies, or tools are badly designed, they can create barriers that exclude people from using the Web. +> +> Accessibility is essential for developers and organizations that want to create high-quality websites and web tools, and not exclude people from using their products and services. +> +> -- [Introduction To Web Accessibility](https://www.w3.org/WAI/fundamentals/accessibility-intro/) + +The standard GoToSocial theme is designed with web accessibility in mind, especially when it comes to layout, color contrasts, font sizes, and so on. + +If you write custom CSS for your profile, it is very important that you make sure that it remains legible and that it behaves as expected. Buttons should look like buttons, links should look like links, text should be presented in a readable font, elements should not jump around the page, etc. Web pages can be pretty and exciting without sacrificing readability, or making things overcomplicated. + +If you change your color scheme, it's a good idea to validate the new colors to make sure that they have sufficient contrast to be readable by people with visual impairments like color blindness. Once you've updated your CSS, try entering your profile URL in a contrast checking tool, like the [Color Contrast Accessibility Validator](https://color.a11y.com/Contrast). You can also use the 'Accessibility' tab in the developer tools of your web browser to check for any issues. + +Styling with accessibility in mind makes the web better for everyone! Have a look at the links below for more information. + +## Useful Links + +- [Learn CSS (Mozilla)](https://developer.mozilla.org/en-US/docs/Learn/CSS) +- [CSS Tutorial (W3 Schools)](https://www.w3schools.com/Css/default.asp) +- [CSS and JavaScript Accessibility Best Practices (Mozilla)](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/CSS_and_JavaScript#css) +- [WAVE Web Accessibility Evaluation Tool](https://wave.webaim.org/) +- [Color Contrast Accessibility Validator](https://color.a11y.com/Contrast) |
