Skip to content

Commit cd7b8f5

Browse files
Matt Pennaaxilleas
Matt Penna
authored and
axilleas
committed
SSoT work on customization docs
Reviewed all docs in the customization section and updated them to adhere to our SSoT standards.
1 parent a445dc2 commit cd7b8f5

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)