Skip to content

Commit 85fc992

Browse files
andrewconnellandrewconnell
committed
Fix validation error "disallowed-___domain"
- cleanup markdown
1 parent 1564ce6 commit 85fc992

6 files changed

+136
-369
lines changed

‎docs/general-development/how-to-make-custom-css-files-themable-in-sharepoint.md

Lines changed: 39 additions & 166 deletions
Original file line numberDiff line numberDiff line change
@@ -1,224 +1,118 @@
11
---
22
title: Make custom CSS files themable in SharePoint
3-
ms.date: 05/20/2020
3+
description: Learn how to add comment-style markup to a CSS file so that it can be used in the SharePoint theming engine.
4+
ms.date: 06/21/2021
45
ms.prod: sharepoint
56
ms.assetid: b8c82c77-c836-47f9-a11e-6c9c656d436b
67
localization_priority: Priority
78
---
8-
9-
109
# Make custom CSS files themable in SharePoint
1110

1211
Learn how to add comment-style markup to a CSS file so that it can be used in the SharePoint theming engine.
1312

1413
## Introduction to annotations
15-
<a name="Intro"> </a>
1614

1715
Annotations are special comment-style markup that tell the SharePoint theming engine how to theme properties in a CSS file. When a theme is applied to a site, the theming engine replaces the CSS property values with the appropriate theme values. In SharePoint, you can use annotations to change the color, font, or background image. You can also recolor an image. If you are using custom CSS files, you must add these annotations to the CSS files if you want to use them with the SharePoint theming engine. If you apply a theme to a site that uses custom CSS files, and you haven't added annotations, the CSS properties remain unchanged. This can result in a site that has a mismatched design.
18-
19-
20-
16+
2117
This article describes the available annotations and how to register CSS files.
22-
23-
24-
18+
2519
For more information about custom themes, see [How to: Deploy a custom theme in SharePoint](how-to-deploy-a-custom-theme-in-sharepoint.md) and [How to: Create a master page preview file in SharePoint](how-to-create-a-master-page-preview-file-in-sharepoint.md).
26-
27-
28-
2920

3021
## Add annotations to custom CSS files
31-
<a name="annotations"> </a>
3222

3323
Annotations tell the SharePoint theming engine how to theme properties in a CSS file. This section describes the available annotations and how they can be used.
34-
35-
36-
3724

3825
### ReplaceColor annotation
39-
<a name="replaceColor"> </a>
4026

4127
The **ReplaceColor** annotation replaces the color value with the specified theme color. It can be used with CSS properties that define a color value, such as **color**, **background-color**, **border**, and so on.
42-
43-
44-
45-
The following shows the format for the **ReplaceColor** annotation.
46-
47-
48-
4928

29+
The following shows the format for the **ReplaceColor** annotation.
5030

51-
52-
```
53-
31+
```css
5432
/* [ReplaceColor(themeColor:"ColorSlot"[, themeShade:"ShadeValue"][, themeTint:"TintValue"][, opacity:"OpacityValue"])] */
55-
5633
```
5734

58-
Replace _ColorSlot_ with the annotation name of the color slot to use. To see a list of available color slots, see the [Color slot mapping](color-palettes-and-fonts-in-sharepoint.md#colorSlots) section in [Color palettes and fonts in SharePoint](color-palettes-and-fonts-in-sharepoint.md).
59-
60-
61-
35+
Replace `ColorSlot` with the annotation name of the color slot to use. To see a list of available color slots, see the [Color slot mapping](color-palettes-and-fonts-in-sharepoint.md#colorSlots) section in [Color palettes and fonts in SharePoint](color-palettes-and-fonts-in-sharepoint.md).
36+
6237
Use the optional **themeShade** parameter if you want to darken the theme color. Replace _ShadeValue_ with a numeric value from 0.0 (no change) to 1.0 (darkest).
63-
64-
65-
38+
6639
Use the optional **themeTint** parameter if you want to lighten the theme color. Replace _TintValue_ with a numeric value from 0.0 (no change) to 1.0 (lightest).
67-
68-
69-
40+
7041
Use the optional **opacity** parameter if you want to specify the opacity of the theme color. Replace _OpacityValue_ with a numeric value that specifies the opacity setting. The opacity setting ranges from 0.0 (fully transparent) to 1.0 (fully opaque).
71-
72-
73-
42+
7443
The following shows examples of the **ReplaceColor** annotation being used in a CSS file.
75-
76-
77-
78-
79-
- `/* [ReplaceColor(themeColor:"BodyText")] */ color:#444;`
80-
81-
82-
- `/* [ReplaceColor(themeColor:"BackgroundOverlay",opacity:"0.5")] */ background-color:#fff;`
83-
84-
85-
- `/* [ReplaceColor(themeColor:"EmphasisBackground",themeTint:"0.05")] */ background-color:#f2faff;`
86-
87-
44+
45+
- `/* [ReplaceColor(themeColor:"BodyText")] */ color:#444;`
46+
- `/* [ReplaceColor(themeColor:"BackgroundOverlay",opacity:"0.5")] */ background-color:#fff;`
47+
- `/* [ReplaceColor(themeColor:"EmphasisBackground",themeTint:"0.05")] */ background-color:#f2faff;`
8848

8949
### ReplaceFont annotation
90-
<a name="replaceFont"> </a>
9150

9251
The **ReplaceFont** annotation adds the specified theme font to the list of available fonts. It can be used with the **font** and **font-family** CSS properties.
93-
94-
95-
96-
The following shows the format for the **ReplaceFont** annotation.
97-
98-
99-
100-
101-
10252

103-
```
53+
The following shows the format for the **ReplaceFont** annotation.
10454

55+
```css
10556
/* [ReplaceFont(themeFont:"FontSlot")] */
10657
```
10758

10859
Replace _FontSlot_ with the name of the font slot to use. To see a list of available font slots, see the [Font slots](color-palettes-and-fonts-in-sharepoint.md#fontSlot) section in [Color palettes and fonts in SharePoint](color-palettes-and-fonts-in-sharepoint.md).
109-
110-
111-
60+
11261
The following shows an example of the **ReplaceFont** annotation. In this example, if the **body** font slot is defined as Courier in the theme, Courier will be added as the first item in the list of available fonts in the **Choose the Look** wizard.
113-
114-
115-
11662

117-
- `/* [ReplaceFont(themeFont:"body")] */ font-family:"Segoe UI","Segoe",Tahoma,Helvetica,Arial,sans-serif;`
118-
119-
63+
- `/* [ReplaceFont(themeFont:"body")] */ font-family:"Segoe UI","Segoe",Tahoma,Helvetica,Arial,sans-serif;`
12064

12165
### ReplaceBGImage annotation
122-
<a name="replaceBGimage"> </a>
12366

12467
The **ReplaceBGImage** annotation replaces the background image in the CSS file with the theme background image. It can be used with the **background** and **background-image** CSS properties.
125-
126-
127-
128-
The following shows the format for the **ReplaceBGImage** annotation. The **ReplaceBGImage** annotation can also be used with the **AlphaImageLoader** filter to support earlier versions of Internet Explorer.
129-
130-
131-
132-
13368

69+
The following shows the format for the **ReplaceBGImage** annotation. The **ReplaceBGImage** annotation can also be used with the **AlphaImageLoader** filter to support earlier versions of Internet Explorer.
13470

135-
```
71+
```css
13672
/* [ReplaceBGImage] */
13773
```
13874

139-
14075
### RecolorImage annotation
141-
<a name="replaceBGimage"> </a>
14276

14377
The **RecolorImage** annotation recolors the image specified.
144-
145-
146-
147-
The following describes the format of the **RecolorImage** annotation.
148-
149-
150-
151-
15278

79+
The following describes the format of the **RecolorImage** annotation.
15380

154-
```
81+
```css
15582
/* [RecolorImage(themeColor:"ColorSlot"[, method:["Tinting"|"Blending"|"Filling"]][, includeRectangle: {x:x-Setting,y:y-Setting,width:RegionWidth,height:RegionHeight})] */
156-
15783
```
15884

15985
Replace _ColorSlot_ with the annotation name of the color slot. To see a list of available color slots, see the [Color slot mapping](color-palettes-and-fonts-in-sharepoint.md#colorSlots) section in [Color palettes and fonts in SharePoint](color-palettes-and-fonts-in-sharepoint.md).
160-
161-
162-
86+
16387
Use the optional **method** parameter if you want to specify the recoloring method.
164-
165-
166-
88+
16789
Use the optional **includeRectangle** parameter if you want to recolor only a specific region of an image. Replace _x-Setting_, _y-Setting_, _RegionWidth_, and _RegionHeight_ with the x-coordinate, y-coordinate, width, and height of the region that you want to recolor.
168-
169-
170-
90+
17191
The following shows examples of the **RecolorImage** annotation being used in a CSS file.
172-
173-
174-
17592

176-
- `/* [RecolorImage(themeColor:"SubtleBodyText",method:"Tinting")] */ background-image:url("/_layouts/15/images/tabtitlerowbottombg.png?rev=23");`
177-
178-
179-
- `/* [RecolorImage(themeColor:"BodyText",method:"Filling",includeRectangle:{x:161,y:178,width:16;height:16})] */ background:url("/_layouts/15/images/spcommon.png?rev=23") no-repeat -161px -178px;`
180-
181-
93+
- `/* [RecolorImage(themeColor:"SubtleBodyText",method:"Tinting")] */ background-image:url("/_layouts/15/images/tabtitlerowbottombg.png?rev=23");`
94+
- `/* [RecolorImage(themeColor:"BodyText",method:"Filling",includeRectangle:{x:161,y:178,width:16;height:16})] */ background:url("/_layouts/15/images/spcommon.png?rev=23") no-repeat -161px -178px;`
18295

18396
## Upload the CSS file to the Themable folder in the Style library
184-
<a name="uploadCSS"> </a>
18597

18698
Place the custom CSS files in the Themable folder in the Style library (not the Themable folder in the Master Page Gallery). Only CSS files that are stored in the Themable folder in the Style library are recognized by the theming engine. The Themable folder is created automatically for publishing sites. Otherwise, you can create the Themable folder in the correct ___location (http:// _SiteCollectionName_/Style Library/ _language_/Themable/).
187-
99+
188100
> [!NOTE]
189-
> The name of the _language_ folder must be in the 4-digit format _ll-cc_ to identify the language and culture, respectively. For example, en-us or ar-sa. For more information, see [Language identifiers and OptionState Id values in Office 2013](https://technet.microsoft.com/library/cc179219.aspx).
190-
191-
192-
101+
> The name of the _language_ folder must be in the 4-digit format _ll-cc_ to identify the language and culture, respectively. For example, en-us or ar-sa. For more information, see [Language identifiers and OptionState Id values in Office 2013](https://technet.microsoft.com/library/cc179219.aspx).
193102
194103
CSS files must be checked in and published. If CSS files are changed, you must reapply the theme for the changes to be recognized.
195-
196-
197-
198104

199105
## Register the CSS file
200-
<a name="registerCSS"> </a>
201106

202107
You must register the CSS file with a master page before the CSS file can be used by the theming engine. This directs the master page to the CSS file when you apply a theme to a site. To register a CSS file, you add a **<SharePoint:CssRegistration>** element to the **<head>** element of the master page. The following shows the format of the **<SharePoint:CssRegistration>** element.
203-
204-
205-
206108

207109
```HTML
208-
209110
<SharePoint:CssRegistration Name="CSSFileLocation" runat="server" />
210111
```
211112

212-
Replace _CSSFileLocation_ with the ___location of the CSS file.
213-
214-
215-
216-
The following is an example of an **<SharePoint:CssRegistration>** element.
217-
218-
219-
220-
113+
Replace _CSSFileLocation_ with the ___location of the CSS file.
221114

115+
The following is an example of an **<SharePoint:CssRegistration>** element.
222116

223117
```HTML
224118
<head>
@@ -229,34 +123,13 @@ The following is an example of an **<SharePoint:CssRegistration>** element.
229123

230124
> [!NOTE]
231125
> The **%$SPUrl** token cannot be used on SharePoint Foundation 2013. You must use a URL to specify the ___location of the CSS file.
232-
233-
234-
235-
236126
237127
## See also
238-
<a name="addresources"> </a>
239-
240-
241-
- [Themes overview for SharePoint](themes-overview-for-sharepoint.md)
242-
243-
244-
- [How to: Deploy a custom theme in SharePoint](how-to-deploy-a-custom-theme-in-sharepoint.md)
245-
246-
247-
- [Upgrade custom themes and CSS to SharePoint](upgrade-custom-themes-and-css-to-sharepoint.md)
248-
249-
250-
- [How to: Create a master page preview file in SharePoint](how-to-create-a-master-page-preview-file-in-sharepoint.md)
251-
252-
253-
- [Color palettes and fonts in SharePoint](color-palettes-and-fonts-in-sharepoint.md)
254-
255-
256-
- [SharePoint Team Blog: Show off your style with SharePoint theming](https://www.microsoft.com/en-us/microsoft-365/blog/2012/10/29/show-off-your-style-with-sharepoint-theming/)
257-
258-
259-
- [SharePoint Design Manager branding and design capabilities](sharepoint-design-manager-branding-and-design-capabilities.md)
260-
261-
262128

129+
- [Themes overview for SharePoint](themes-overview-for-sharepoint.md)
130+
- [How to: Deploy a custom theme in SharePoint](how-to-deploy-a-custom-theme-in-sharepoint.md)
131+
- [Upgrade custom themes and CSS to SharePoint](upgrade-custom-themes-and-css-to-sharepoint.md)
132+
- [How to: Create a master page preview file in SharePoint](how-to-create-a-master-page-preview-file-in-sharepoint.md)
133+
- [Color palettes and fonts in SharePoint](color-palettes-and-fonts-in-sharepoint.md)
134+
- [SharePoint Team Blog: Show off your style with SharePoint theming](https://www.microsoft.com/microsoft-365/blog/2012/10/29/show-off-your-style-with-sharepoint-theming/)
135+
- [SharePoint Design Manager branding and design capabilities](sharepoint-design-manager-branding-and-design-capabilities.md)

0 commit comments

Comments
 (0)