Skip to content

Commit f6a201a

Browse files
axilleasaxilleas
committed
Merge branch 'docs-ssot-customization' into 'master'
SSoT for customization docs Closes #64588 See merge request gitlab-org/gitlab-ce!31308
2 parents a445dc2 + cd7b8f5 commit f6a201a

7 files changed

+192
-66
lines changed

‎doc/customization/branded_login_page.md

Lines changed: 27 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,38 @@
1-
# Changing the appearance of the login page
1+
---
2+
type: howto
3+
---
24

3-
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.
5+
# Changing the logo and description on the login page
46

5-
By default, the page shows the GitLab logo and description.
7+
You can customize the login page of your GitLab server to show the logo and
8+
description of your organization.
9+
10+
By default, the page shows the GitLab logo and description:
611

712
![default_login_page](branded_login_page/default_login_page.png)
813

9-
## Changing the appearance of the login page
14+
To customize the login page:
1015

11-
Navigate to the **Admin** area and go to the **Appearance** page.
16+
1. Navigate to the **Admin** area and go to the **Appearance** page.
17+
1. Fill in your desired Title and Description. You can also choose an image file
18+
of the logo for your organization.
1219

13-
Fill in the required details like Title, Description and upload the company logo.
20+
![appearance](branded_login_page/appearance.png)
1421

15-
![appearance](branded_login_page/appearance.png)
22+
1. Save your changes.
1623

17-
After saving the page, your GitLab login page will have the details you filled in:
24+
Your GitLab login page will display the details you provided:
1825

1926
![company_login_page](branded_login_page/custom_sign_in.png)
27+
28+
<!-- ## Troubleshooting
29+
30+
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
31+
one might have when setting this up, or when something is changed, or on upgrading, it's
32+
important to describe those, too. Think of things that may go wrong and include them here.
33+
This is important to minimize requests for support, and to avoid doc comments with
34+
questions that you know someone might ask.
35+
36+
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
37+
If you have none to add when creating a doc, leave this section in place
38+
but commented out to help encourage others to add to it in the future. -->

‎doc/customization/branded_page_and_email_header.md

Lines changed: 28 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,37 @@
1-
# Changing the logo on the overall page and email header
1+
---
2+
type: howto
3+
---
24

3-
Navigate to the **Admin** area and go to the **Appearance** page.
5+
# Changing the navigation bar and email header logo
46

5-
Upload the custom logo (**Header logo**) in the section **Navigation bar**.
7+
You can customize the logo that appears in email headers and in the navigation
8+
bar on pages that are displayed by your GitLab server.
69

7-
![appearance](branded_page_and_email_header/appearance.png)
10+
1. Navigate to the **Admin** area and go to the **Appearance** page, then locate
11+
the **Navigation bar** section.
12+
1. For the **Header Logo**, choose an image file of the logo for your
13+
organization.
814

9-
After saving the page, your GitLab navigation bar will contain the custom logo:
15+
![appearance](branded_page_and_email_header/appearance.png)
16+
17+
1. Save your changes.
18+
19+
Your GitLab navigation bar will display the custom logo:
1020

1121
![custom_brand_header](branded_page_and_email_header/custom_brand_header.png)
1222

13-
The GitLab pipeline emails will also have the custom logo:
23+
The GitLab pipeline emails will also display the custom logo:
1424

1525
![custom_email_header](branded_page_and_email_header/custom_email_header.png)
26+
27+
<!-- ## Troubleshooting
28+
29+
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
30+
one might have when setting this up, or when something is changed, or on upgrading, it's
31+
important to describe those, too. Think of things that may go wrong and include them here.
32+
This is important to minimize requests for support, and to avoid doc comments with
33+
questions that you know someone might ask.
34+
35+
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
36+
If you have none to add when creating a doc, leave this section in place
37+
but commented out to help encourage others to add to it in the future. -->

‎doc/customization/favicon.md

Lines changed: 26 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,37 @@
1+
---
2+
type: howto
3+
---
4+
15
# Changing the favicon
26

37
> [Introduced][ce-14497] in GitLab 11.0.
48
59
[ce-14497]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14497
610

7-
Navigate to the **Admin** area and go to the **Appearance** page.
11+
You can customize the favicon (the icon displayed in your web browser's
12+
address bar and web page tabs) for your GitLab server.
13+
14+
1. Navigate to the **Admin** area and go to the **Appearance** page, then
15+
locate the **Favicon** section.
16+
1. Upload an image file of your favicon.
817

9-
Upload the custom favicon (**Favicon**) in the section **Favicon**.
18+
![appearance](favicon/appearance.png)
1019

11-
![appearance](favicon/appearance.png)
20+
1. Save your changes.
1221

13-
After saving the page, the new favicon will be shown in the browser. The main
14-
favicon as well as the CI status icons will show the custom icon:
22+
Your new favicon will display in the browser. The main favicon and the CI
23+
status icons will show the custom icon:
1524

1625
![custom_favicon](favicon/custom_favicon.png)
26+
27+
<!-- ## Troubleshooting
28+
29+
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
30+
one might have when setting this up, or when something is changed, or on upgrading, it's
31+
important to describe those, too. Think of things that may go wrong and include them here.
32+
This is important to minimize requests for support, and to avoid doc comments with
33+
questions that you know someone might ask.
34+
35+
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
36+
If you have none to add when creating a doc, leave this section in place
37+
but commented out to help encourage others to add to it in the future. -->

‎doc/customization/help_message.md

Lines changed: 30 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,36 @@
1-
# GitLab Help custom text
1+
---
2+
type: howto
3+
---
24

3-
In larger organizations it is useful to have information about who has the responsibility of maintaining the company GitLab server.
5+
# Customizing the 'Help' and login page messages
46

5-
1. Navigate to the admin area, click on **Preferences** and expand **Help page**.
7+
In large organizations, it is useful to have information about who maintains
8+
the company GitLab server. You can customize and display this information on
9+
the GitLab login page and on the GitLab server's `/help` page.
610

7-
1. Under **Help text** fill in the required information about the person(s) administering GitLab or any other information relevant to your needs.
11+
1. Navigate to the **Admin** area, then click on **Preferences** and expand
12+
**Help page**.
13+
1. Under **Help page text**, fill in the required information about the
14+
person(s) administering GitLab. This text can also contain any other
15+
information that you wish to display to users.
816

9-
![help message](help_message/help_text.png)
17+
![help message](help_message/help_text.png)
1018

11-
1. After saving the page this information will be shown on the GitLab login page and on the GitLab `/help` page (e.g., <https://gitlab.com/help>).
19+
1. Save your changes.
1220

13-
![help text on help page](help_message/help_text_on_help_page.png)
21+
The information you entered will be shown on the GitLab login page and on the
22+
GitLab `/help` page (e.g., <https://gitlab.com/help>).
23+
24+
![help text on help page](help_message/help_text_on_help_page.png)
25+
26+
<!-- ## Troubleshooting
27+
28+
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
29+
one might have when setting this up, or when something is changed, or on upgrading, it's
30+
important to describe those, too. Think of things that may go wrong and include them here.
31+
This is important to minimize requests for support, and to avoid doc comments with
32+
questions that you know someone might ask.
33+
34+
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
35+
If you have none to add when creating a doc, leave this section in place
36+
but commented out to help encourage others to add to it in the future. -->

‎doc/customization/index.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
11
---
2+
type: index
23
description: Learn how to customize GitLab's appearance for self-managed installations.
34
---
45

56
# Customizing GitLab's appearance **(CORE ONLY)**
67

7-
For GitLab self-managed instances, it's possible to customize
8-
a few pages.
8+
For GitLab self-managed instances, you can customize the page logo,
9+
email headers, favicon, and several other aspects of GitLab's appearance.
910

10-
Read through the following documents to adjust GitLab's
11-
look and feel to meet your needs:
11+
The following pages explain how to customize the appearance of your instance:
1212

13-
- [Custom login page](branded_login_page.md)
14-
- [Custom header and email logo](branded_page_and_email_header.md)
15-
- [Custom favicon](favicon.md)
16-
- [Libravatar](libravatar.md)
17-
- [New project page](new_project_page.md)
18-
- [Custom `/help` message](help_message.md)
13+
- [Changing the logo and description on the login page](branded_login_page.md)
14+
- [Changing the navigation bar and email header logo](branded_page_and_email_header.md)
15+
- [Changing the favicon](favicon.md)
16+
- [Customizing the new project page](new_project_page.md)
17+
- [Customizing the `/help` and login page messages](help_message.md)
18+
- [Using the Libravatar service with GitLab](libravatar.md)

‎doc/customization/libravatar.md

Lines changed: 44 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,20 @@
1-
# Use Libravatar service with GitLab
1+
---
2+
type: howto
3+
---
24

3-
GitLab by default supports [Gravatar](https://gravatar.com) avatar service.
4-
Libravatar is a service which delivers your avatar (profile picture) to other websites and their API is
5-
[heavily based on gravatar](https://wiki.libravatar.org/api/).
5+
# Using the Libravatar service with GitLab
66

7-
This means that it is not complicated to switch to Libravatar avatar service or even self hosted Libravatar server.
7+
GitLab by default supports the [Gravatar](https://gravatar.com) avatar service.
8+
9+
Libravatar is another service that delivers your avatar (profile picture) to
10+
other websites. The Libravatar API is
11+
[heavily based on gravatar](https://wiki.libravatar.org/api/), so you can
12+
easily switch to the Libravatar avatar service or even a self-hosted Libravatar
13+
server.
814

915
## Configuration
1016

11-
In [gitlab.yml gravatar section](https://gitlab.com/gitlab-org/gitlab-ce/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122) set
17+
In the [gitlab.yml gravatar section](https://gitlab.com/gitlab-org/gitlab-ce/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122), set
1218
the configuration options as follows:
1319

1420
### For HTTP
@@ -29,50 +35,67 @@ the configuration options as follows:
2935
ssl_url: "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
3036
```
3137
32-
### Self-hosted
38+
### Self-hosted Libravatar server
3339
34-
If you are [running your own libravatar service](https://wiki.libravatar.org/running_your_own/) the URL will be different in the configuration
35-
but the important part is to provide the same placeholders so GitLab can parse the URL correctly.
40+
If you are [running your own libravatar service](https://wiki.libravatar.org/running_your_own/),
41+
the URL will be different in the configuration, but you must provide the same
42+
placeholders so GitLab can parse the URL correctly.
3643
37-
For example, you host a service on `http://libravatar.example.com` the `plain_url` you need to supply in `gitlab.yml` is
44+
For example, you host a service on `http://libravatar.example.com` and the
45+
`plain_url` you need to supply in `gitlab.yml` is
3846

3947
`http://libravatar.example.com/avatar/%{hash}?s=%{size}&d=identicon`
4048

4149
### Omnibus-gitlab example
4250

4351
In `/etc/gitlab/gitlab.rb`:
4452

45-
#### For http
53+
#### For HTTP
4654

4755
```ruby
4856
gitlab_rails['gravatar_enabled'] = true
4957
gitlab_rails['gravatar_plain_url'] = "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
5058
```
5159

52-
#### For https
60+
#### For HTTPS
5361

5462
```ruby
5563
gitlab_rails['gravatar_enabled'] = true
5664
gitlab_rails['gravatar_ssl_url'] = "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
5765
```
5866

59-
Run `sudo gitlab-ctl reconfigure` for changes to take effect.
67+
Then run `sudo gitlab-ctl reconfigure` for the changes to take effect.
6068

6169
## Default URL for missing images
6270

63-
[Libravatar supports different sets](https://wiki.libravatar.org/api/) of `missing images` for emails not found on the Libravatar service.
64-
65-
In order to use a different set other than `identicon`, replace `&d=identicon` portion of the URL with another supported set.
66-
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"`
71+
[Libravatar supports different sets](https://wiki.libravatar.org/api/) of
72+
missing images for user email addresses that are not found on the Libravatar
73+
service.
6774

68-
## Usage examples
75+
In order to use a set other than `identicon`, replace the `&d=identicon`
76+
portion of the URL with another supported set.
77+
For example, you can use the `retro` set, in which case the URL would look like:
78+
`plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=retro"`
6979
70-
### For Microsoft Office 365
80+
## Usage examples for Microsoft Office 365
7181
72-
If your users are Office 365-users, the "GetPersonaPhoto" service can be used. Note that this service requires login, so this use case is
73-
most useful in a corporate installation, where all users have access to Office 365.
82+
If your users are Office 365 users, the `GetPersonaPhoto` service can be used.
83+
Note that this service requires a login, so this use case is most useful in a
84+
corporate installation where all users have access to Office 365.
7485

7586
```ruby
7687
gitlab_rails['gravatar_plain_url'] = 'http://outlook.office365.com/owa/service.svc/s/GetPersonaPhoto?email=%{email}&size=HR120x120'
7788
gitlab_rails['gravatar_ssl_url'] = 'https://outlook.office365.com/owa/service.svc/s/GetPersonaPhoto?email=%{email}&size=HR120x120'
7889
```
90+
91+
<!-- ## Troubleshooting
92+
93+
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
94+
one might have when setting this up, or when something is changed, or on upgrading, it's
95+
important to describe those, too. Think of things that may go wrong and include them here.
96+
This is important to minimize requests for support, and to avoid doc comments with
97+
questions that you know someone might ask.
98+
99+
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
100+
If you have none to add when creating a doc, leave this section in place
101+
but commented out to help encourage others to add to it in the future. -->

‎doc/customization/new_project_page.md

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,38 @@
1+
---
2+
type: howto
3+
---
4+
15
# Customizing the new project page
26

3-
It is possible to add a markdown-formatted message to your GitLab
4-
new project page.
7+
You can add a markdown-formatted message to your GitLab new project page.
58

69
By default, the new project page shows a sidebar with general information:
710

8-
![](new_project_page/default_new_project_page.png)
11+
![default_new_project_page](new_project_page/default_new_project_page.png)
12+
13+
To customize the information in the sidebar:
14+
15+
1. Navigate to the **Admin** area and go to the **Appearance** page, then
16+
locate the **New project pages** section.
17+
1. Fill in your new project project guidelines:
18+
19+
![appearance_settings](new_project_page/appearance_settings.png)
920

10-
## Changing the appearance of the new project page
21+
1. Save the page.
1122

12-
Navigate to the **Admin** area and go to the **Appearance** page.
23+
Your new project page will show the customized guidelines in the sidebar, below
24+
the general information:
1325

14-
Fill in your project guidelines:
26+
![custom_new_project_page](new_project_page/custom_new_project_page.png)
1527

16-
![](new_project_page/appearance_settings.png)
28+
<!-- ## Troubleshooting
1729
18-
After saving the page, your new project page will show the guidelines in the sidebar, below the general information:
30+
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
31+
one might have when setting this up, or when something is changed, or on upgrading, it's
32+
important to describe those, too. Think of things that may go wrong and include them here.
33+
This is important to minimize requests for support, and to avoid doc comments with
34+
questions that you know someone might ask.
1935
20-
![](new_project_page/custom_new_project_page.png)
36+
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
37+
If you have none to add when creating a doc, leave this section in place
38+
but commented out to help encourage others to add to it in the future. -->

0 commit comments

Comments
 (0)