From cd7b8f5f8378e6d4d98f12ee2de5c9e0ae5118f9 Mon Sep 17 00:00:00 2001 From: Matt Penna Date: Tue, 6 Aug 2019 11:10:46 +0000 Subject: SSoT work on customization docs Reviewed all docs in the customization section and updated them to adhere to our SSoT standards. --- doc/customization/branded_login_page.md | 35 +++++++++--- doc/customization/branded_page_and_email_header.md | 34 +++++++++-- doc/customization/favicon.md | 31 +++++++++-- doc/customization/help_message.md | 37 +++++++++--- doc/customization/index.md | 20 +++---- doc/customization/libravatar.md | 65 +++++++++++++++------- doc/customization/new_project_page.md | 36 +++++++++--- 7 files changed, 192 insertions(+), 66 deletions(-) diff --git a/doc/customization/branded_login_page.md b/doc/customization/branded_login_page.md index b892f59d777..afcc2b71284 100644 --- a/doc/customization/branded_login_page.md +++ b/doc/customization/branded_login_page.md @@ -1,19 +1,38 @@ -# Changing the appearance of the login page +--- +type: howto +--- -GitLab offers a way to put your company's identity on the login page of your GitLab server and make it a branded login page. +# Changing the logo and description on the login page -By default, the page shows the GitLab logo and description. +You can customize the login page of your GitLab server to show the logo and +description of your organization. + +By default, the page shows the GitLab logo and description: ![default_login_page](branded_login_page/default_login_page.png) -## Changing the appearance of the login page +To customize the login page: -Navigate to the **Admin** area and go to the **Appearance** page. +1. Navigate to the **Admin** area and go to the **Appearance** page. +1. Fill in your desired Title and Description. You can also choose an image file + of the logo for your organization. -Fill in the required details like Title, Description and upload the company logo. + ![appearance](branded_login_page/appearance.png) -![appearance](branded_login_page/appearance.png) +1. Save your changes. -After saving the page, your GitLab login page will have the details you filled in: +Your GitLab login page will display the details you provided: ![company_login_page](branded_login_page/custom_sign_in.png) + + diff --git a/doc/customization/branded_page_and_email_header.md b/doc/customization/branded_page_and_email_header.md index 9a0f0b382fa..370c1461d30 100644 --- a/doc/customization/branded_page_and_email_header.md +++ b/doc/customization/branded_page_and_email_header.md @@ -1,15 +1,37 @@ -# Changing the logo on the overall page and email header +--- +type: howto +--- -Navigate to the **Admin** area and go to the **Appearance** page. +# Changing the navigation bar and email header logo -Upload the custom logo (**Header logo**) in the section **Navigation bar**. +You can customize the logo that appears in email headers and in the navigation +bar on pages that are displayed by your GitLab server. -![appearance](branded_page_and_email_header/appearance.png) +1. Navigate to the **Admin** area and go to the **Appearance** page, then locate + the **Navigation bar** section. +1. For the **Header Logo**, choose an image file of the logo for your + organization. -After saving the page, your GitLab navigation bar will contain the custom logo: + ![appearance](branded_page_and_email_header/appearance.png) + +1. Save your changes. + +Your GitLab navigation bar will display the custom logo: ![custom_brand_header](branded_page_and_email_header/custom_brand_header.png) -The GitLab pipeline emails will also have the custom logo: +The GitLab pipeline emails will also display the custom logo: ![custom_email_header](branded_page_and_email_header/custom_email_header.png) + + diff --git a/doc/customization/favicon.md b/doc/customization/favicon.md index 45a18159b5e..dbde6e8c03b 100644 --- a/doc/customization/favicon.md +++ b/doc/customization/favicon.md @@ -1,16 +1,37 @@ +--- +type: howto +--- + # Changing the favicon > [Introduced][ce-14497] in GitLab 11.0. [ce-14497]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14497 -Navigate to the **Admin** area and go to the **Appearance** page. +You can customize the favicon (the icon displayed in your web browser's +address bar and web page tabs) for your GitLab server. + +1. Navigate to the **Admin** area and go to the **Appearance** page, then + locate the **Favicon** section. +1. Upload an image file of your favicon. -Upload the custom favicon (**Favicon**) in the section **Favicon**. + ![appearance](favicon/appearance.png) -![appearance](favicon/appearance.png) +1. Save your changes. -After saving the page, the new favicon will be shown in the browser. The main -favicon as well as the CI status icons will show the custom icon: +Your new favicon will display in the browser. The main favicon and the CI +status icons will show the custom icon: ![custom_favicon](favicon/custom_favicon.png) + + diff --git a/doc/customization/help_message.md b/doc/customization/help_message.md index c2e592d03bf..a4d8f295750 100644 --- a/doc/customization/help_message.md +++ b/doc/customization/help_message.md @@ -1,13 +1,36 @@ -# GitLab Help custom text +--- +type: howto +--- -In larger organizations it is useful to have information about who has the responsibility of maintaining the company GitLab server. +# Customizing the 'Help' and login page messages -1. Navigate to the admin area, click on **Preferences** and expand **Help page**. +In large organizations, it is useful to have information about who maintains +the company GitLab server. You can customize and display this information on +the GitLab login page and on the GitLab server's `/help` page. -1. Under **Help text** fill in the required information about the person(s) administering GitLab or any other information relevant to your needs. +1. Navigate to the **Admin** area, then click on **Preferences** and expand + **Help page**. +1. Under **Help page text**, fill in the required information about the + person(s) administering GitLab. This text can also contain any other + information that you wish to display to users. - ![help message](help_message/help_text.png) + ![help message](help_message/help_text.png) -1. After saving the page this information will be shown on the GitLab login page and on the GitLab `/help` page (e.g., ). +1. Save your changes. - ![help text on help page](help_message/help_text_on_help_page.png) +The information you entered will be shown on the GitLab login page and on the +GitLab `/help` page (e.g., ). + +![help text on help page](help_message/help_text_on_help_page.png) + + diff --git a/doc/customization/index.md b/doc/customization/index.md index 0198059297f..f17a2d80e2c 100644 --- a/doc/customization/index.md +++ b/doc/customization/index.md @@ -1,18 +1,18 @@ --- +type: index description: Learn how to customize GitLab's appearance for self-managed installations. --- # Customizing GitLab's appearance **(CORE ONLY)** -For GitLab self-managed instances, it's possible to customize -a few pages. +For GitLab self-managed instances, you can customize the page logo, +email headers, favicon, and several other aspects of GitLab's appearance. -Read through the following documents to adjust GitLab's -look and feel to meet your needs: +The following pages explain how to customize the appearance of your instance: -- [Custom login page](branded_login_page.md) -- [Custom header and email logo](branded_page_and_email_header.md) -- [Custom favicon](favicon.md) -- [Libravatar](libravatar.md) -- [New project page](new_project_page.md) -- [Custom `/help` message](help_message.md) \ No newline at end of file +- [Changing the logo and description on the login page](branded_login_page.md) +- [Changing the navigation bar and email header logo](branded_page_and_email_header.md) +- [Changing the favicon](favicon.md) +- [Customizing the new project page](new_project_page.md) +- [Customizing the `/help` and login page messages](help_message.md) +- [Using the Libravatar service with GitLab](libravatar.md) diff --git a/doc/customization/libravatar.md b/doc/customization/libravatar.md index e618f3be2fe..1c3bf877fa1 100644 --- a/doc/customization/libravatar.md +++ b/doc/customization/libravatar.md @@ -1,14 +1,20 @@ -# Use Libravatar service with GitLab +--- +type: howto +--- -GitLab by default supports [Gravatar](https://gravatar.com) avatar service. -Libravatar is a service which delivers your avatar (profile picture) to other websites and their API is -[heavily based on gravatar](https://wiki.libravatar.org/api/). +# Using the Libravatar service with GitLab -This means that it is not complicated to switch to Libravatar avatar service or even self hosted Libravatar server. +GitLab by default supports the [Gravatar](https://gravatar.com) avatar service. + +Libravatar is another service that delivers your avatar (profile picture) to +other websites. The Libravatar API is +[heavily based on gravatar](https://wiki.libravatar.org/api/), so you can +easily switch to the Libravatar avatar service or even a self-hosted Libravatar +server. ## Configuration -In [gitlab.yml gravatar section](https://gitlab.com/gitlab-org/gitlab-ce/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122) set +In the [gitlab.yml gravatar section](https://gitlab.com/gitlab-org/gitlab-ce/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122), set the configuration options as follows: ### For HTTP @@ -29,12 +35,14 @@ the configuration options as follows: ssl_url: "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon" ``` -### Self-hosted +### Self-hosted Libravatar server -If you are [running your own libravatar service](https://wiki.libravatar.org/running_your_own/) the URL will be different in the configuration -but the important part is to provide the same placeholders so GitLab can parse the URL correctly. +If you are [running your own libravatar service](https://wiki.libravatar.org/running_your_own/), +the URL will be different in the configuration, but you must provide the same +placeholders so GitLab can parse the URL correctly. -For example, you host a service on `http://libravatar.example.com` the `plain_url` you need to supply in `gitlab.yml` is +For example, you host a service on `http://libravatar.example.com` and the +`plain_url` you need to supply in `gitlab.yml` is `http://libravatar.example.com/avatar/%{hash}?s=%{size}&d=identicon` @@ -42,37 +50,52 @@ For example, you host a service on `http://libravatar.example.com` the `plain_ur In `/etc/gitlab/gitlab.rb`: -#### For http +#### For HTTP ```ruby gitlab_rails['gravatar_enabled'] = true gitlab_rails['gravatar_plain_url'] = "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon" ``` -#### For https +#### For HTTPS ```ruby gitlab_rails['gravatar_enabled'] = true gitlab_rails['gravatar_ssl_url'] = "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon" ``` -Run `sudo gitlab-ctl reconfigure` for changes to take effect. +Then run `sudo gitlab-ctl reconfigure` for the changes to take effect. ## Default URL for missing images -[Libravatar supports different sets](https://wiki.libravatar.org/api/) of `missing images` for emails not found on the Libravatar service. - -In order to use a different set other than `identicon`, replace `&d=identicon` portion of the URL with another supported set. -For example, you can use `retro` set in which case the URL would look like: `plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=retro"` +[Libravatar supports different sets](https://wiki.libravatar.org/api/) of +missing images for user email addresses that are not found on the Libravatar +service. -## Usage examples +In order to use a set other than `identicon`, replace the `&d=identicon` +portion of the URL with another supported set. +For example, you can use the `retro` set, in which case the URL would look like: +`plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=retro"` -### For Microsoft Office 365 +## Usage examples for Microsoft Office 365 -If your users are Office 365-users, the "GetPersonaPhoto" service can be used. Note that this service requires login, so this use case is -most useful in a corporate installation, where all users have access to Office 365. +If your users are Office 365 users, the `GetPersonaPhoto` service can be used. +Note that this service requires a login, so this use case is most useful in a +corporate installation where all users have access to Office 365. ```ruby gitlab_rails['gravatar_plain_url'] = 'http://outlook.office365.com/owa/service.svc/s/GetPersonaPhoto?email=%{email}&size=HR120x120' gitlab_rails['gravatar_ssl_url'] = 'https://outlook.office365.com/owa/service.svc/s/GetPersonaPhoto?email=%{email}&size=HR120x120' ``` + + diff --git a/doc/customization/new_project_page.md b/doc/customization/new_project_page.md index 148bf9512c6..43b95a76d08 100644 --- a/doc/customization/new_project_page.md +++ b/doc/customization/new_project_page.md @@ -1,20 +1,38 @@ +--- +type: howto +--- + # Customizing the new project page -It is possible to add a markdown-formatted message to your GitLab -new project page. +You can add a markdown-formatted message to your GitLab new project page. By default, the new project page shows a sidebar with general information: -![](new_project_page/default_new_project_page.png) +![default_new_project_page](new_project_page/default_new_project_page.png) + +To customize the information in the sidebar: + +1. Navigate to the **Admin** area and go to the **Appearance** page, then + locate the **New project pages** section. +1. Fill in your new project project guidelines: + + ![appearance_settings](new_project_page/appearance_settings.png) -## Changing the appearance of the new project page +1. Save the page. -Navigate to the **Admin** area and go to the **Appearance** page. +Your new project page will show the customized guidelines in the sidebar, below +the general information: -Fill in your project guidelines: +![custom_new_project_page](new_project_page/custom_new_project_page.png) -![](new_project_page/appearance_settings.png) + -- cgit v1.2.1