Skip to content

Fix/custom layout build #5672

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

Fix/custom layout build #5672

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c7fa422
Add prerequisites for custom layout design
drsamitha Oct 21, 2025
87de569
Enhance custom layout guide with notes and tips
drsamitha Oct 22, 2025
68a0f5e
Fix formatting of tip
drsamitha Oct 22, 2025
10e5362
Revise Maven environment variable and links
drsamitha Oct 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 15 additions & 3 deletions en/includes/guides/branding/add-custom-layouts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

- `authenticationendpoint`
- `accountrecoveryendpoint`
- `x509certificateauthenticationendpoint`

Check failure on line 9 in en/includes/guides/branding/add-custom-layouts.md

View workflow job for this annotation

GitHub Actions / lint

Unordered list indentation 

en/includes/guides/branding/add-custom-layouts.md:9:1 MD007/ul-indent Unordered list indentation [Expected: 0; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md007.md

Check failure on line 9 in en/includes/guides/branding/add-custom-layouts.md

View workflow job for this annotation

GitHub Actions / lint

Inconsistent indentation for list items at the same level 

en/includes/guides/branding/add-custom-layouts.md:9:1 MD005/list-indent Inconsistent indentation for list items at the same level [Expected: 0; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md005.md

## General components of the UI

Expand All @@ -19,7 +19,7 @@
This section explains the special syntax that you can use to create a custom layout.

- **Condition block**

Check failure on line 22 in en/includes/guides/branding/add-custom-layouts.md

View workflow job for this annotation

GitHub Actions / lint

Trailing spaces 

en/includes/guides/branding/add-custom-layouts.md:22:1 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 4] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md009.md
This is similar to an `IF` block. In the following example, the condition block will activate or deactivate according to the value of the `isPolicyPage` variable.

```html hl_lines="1 17"
Expand All @@ -43,13 +43,13 @@
{{/isPolicyPage}}
{% endraw %}
```

Check failure on line 46 in en/includes/guides/branding/add-custom-layouts.md

View workflow job for this annotation

GitHub Actions / lint

Trailing spaces 

en/includes/guides/branding/add-custom-layouts.md:46:1 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 4] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md009.md
- If the value of `isPolicyPage` is `true` or any non-empty string, then the content inside the block will be executed.

Check failure on line 47 in en/includes/guides/branding/add-custom-layouts.md

View workflow job for this annotation

GitHub Actions / lint

Unordered list indentation 

en/includes/guides/branding/add-custom-layouts.md:47:1 MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 4] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md007.md
- For all other values including `null` and `undefined`, the content of the block will not be executed.

Check failure on line 48 in en/includes/guides/branding/add-custom-layouts.md

View workflow job for this annotation

GitHub Actions / lint

Unordered list indentation 

en/includes/guides/branding/add-custom-layouts.md:48:1 MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 4] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md007.md

- **Not Condition Block**

This is similar to an `IF` block but with a NOT condition.

Check failure on line 52 in en/includes/guides/branding/add-custom-layouts.md

View workflow job for this annotation

GitHub Actions / lint

Trailing spaces 

en/includes/guides/branding/add-custom-layouts.md:52:63 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md009.md

```html hl_lines="1 12"
{% raw %}
Expand All @@ -68,8 +68,8 @@
{% endraw %}

```

Check failure on line 71 in en/includes/guides/branding/add-custom-layouts.md

View workflow job for this annotation

GitHub Actions / lint

Trailing spaces 

en/includes/guides/branding/add-custom-layouts.md:71:1 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 4] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md009.md
- If the value of `isPolicyPage` is `false`, an empty string, `null` or `undefined`, the content inside the block will be executed.

Check failure on line 72 in en/includes/guides/branding/add-custom-layouts.md

View workflow job for this annotation

GitHub Actions / lint

Trailing spaces 

en/includes/guides/branding/add-custom-layouts.md:72:136 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md009.md

Check failure on line 72 in en/includes/guides/branding/add-custom-layouts.md

View workflow job for this annotation

GitHub Actions / lint

Unordered list indentation 

en/includes/guides/branding/add-custom-layouts.md:72:1 MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 4] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md007.md
- For all other values, the content of the block will not be executed.

- **Component Syntax**
Expand Down Expand Up @@ -167,11 +167,23 @@

### Step 3: Add a custom layout design

To add a custom layout to the login page:
Prerequisites
- `NodeJS v20.x`
- `npm v8.x`
- `PNPM v8.x `
- `yarn v1.22.x`
Comment on lines +172 to +174
Copy link
Contributor

@DilshanSenarath DilshanSenarath Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you verify that the repository builds successfully with all of these package managers?

Copy link
Member

@brionmario brionmario Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

identity-apps only works with pnpm.

Can we have a screenshot of a successful build to confirm your changes are working?

@drsamitha

Copy link
Author

@drsamitha drsamitha Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the responses! I’m honestly not confident about this PR yet and I think this is also not enough for address the issue. Could you please suggest some instructions or a guide to help make the fix?

Also, what if we additionally add two separate scripts for Windows and Linux to the documentation section that automate the confusing copy-pasting and build steps? That should help reduce dependency failure errors, right? For now i use this basic script,

#!/usr/bin/env bash
set -e

if [ $# -ne 2 ]; then
    echo "Usage: $0 <IS_HOME_PATH> <IDENTITY_APPS_HOME_PATH>"
    exit 1
fi

IS_HOME="$1"
IDENTITY_APPS_HOME="$2"

WEBAPPS="$IS_HOME/repository/deployment/server/webapps"
AUTH_EP="$WEBAPPS/authenticationendpoint"
EXTENSIONS_DIR="$AUTH_EP/extensions/layouts/custom/carbon.super"
ASSETS_DIR="$EXTENSIONS_DIR/assets"

LAYOUT_SRC_DIR="$IDENTITY_APPS_HOME/identity-apps-core/components/login-portal-layouts/layouts"
LAYOUT_BUILD_DIR="$IDENTITY_APPS_HOME/identity-apps-core/components/login-portal-layouts"
LAYOUT_COMPILED_DST="$IDENTITY_APPS_HOME/identity-apps-core/apps/authentication-portal/src/main/webapp/extensions/layouts"
FINAL_DST="$AUTH_EP/extensions/layouts"

echo "==> Creating folder structure under Identity Server..."
mkdir -p "$ASSETS_DIR"

echo "==> Downloading layout files..."
curl -L -o "$EXTENSIONS_DIR/body.html" "https://raw.githubusercontent.com/wso2/docs-is/master/en/identity-server/7.2.0/docs/assets/code-samples/body.html"
curl -L -o "$EXTENSIONS_DIR/styles.css" "https://raw.githubusercontent.com/wso2/docs-is/master/en/identity-server/7.2.0/docs/assets/code-samples/style.css"
curl -L -o "$EXTENSIONS_DIR/script.js" "https://raw.githubusercontent.com/wso2/docs-is/master/en/identity-server/7.2.0/docs/assets/code-samples/script.js"
curl -L -o "$ASSETS_DIR/illustration.svg" "https://raw.githubusercontent.com/wso2/docs-is/master/en/identity-server/7.2.0/docs/assets/code-samples/illustration.svg"

echo "==> Copying custom layout to Identity Apps source tree..."
mkdir -p "$LAYOUT_SRC_DIR"
cp -r "$AUTH_EP/extensions/layouts/custom" "$LAYOUT_SRC_DIR/"

echo "==> Building Identity Apps (this may take a while)..."
cd "$LAYOUT_BUILD_DIR"
mvn clean install -q

echo "==> Copying compiled layout back to Identity Server..."
mkdir -p "$FINAL_DST"
cp -r "$LAYOUT_COMPILED_DST/custom" "$FINAL_DST/"

echo "==> All done!"
echo
echo "Your custom layout has been built and applied to the Identity Server."
echo "If the server was running, restart it before verifying the login page."
echo
echo "Custom layout directory: $FINAL_DST/custom"

Copy link
Author

@drsamitha drsamitha Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you verify that the repository builds successfully with all of these package managers?

Only with the pnpm.

Copy link
Author

@drsamitha drsamitha Nov 7, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

identity-apps only works with pnpm.

Can we have a screenshot of a successful build to confirm your changes are working?

@drsamitha

did u mean Screenshots of custom layout builds?
if so, Identity apps successfully build the custom layout pages.
PS - browser messed up the theme
image

TBH, i cant remember why i have included the other package managers.

- `JDK 11`

!!! note
Make sure the build server has an active Internet connection to download dependencies while building.

!!! tip
Go through the [troubleshooting guides]([https://wso2.github.io/using-maven.html](https://github.com/wso2/identity-apps/blob/master/docs/TROUBLESHOOTING.md)).

To add a custom layout to the login page:
1. Navigate to `webapps/authenticationendpoint/extensions/layouts/custom/carbon.super/` and follow the instructions provided below:

1. Copy the code snippet from the [html file](https://github.com/wso2/docs-is/tree/master/en/identity-server/{{is_version}}/docs/assets/code-samples/body.html){target="_blank"} into the `body.html` file.

Check warning on line 186 in en/includes/guides/branding/add-custom-layouts.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[WSO2-IAM.Spelling] Did you really mean 'html'?

Raw Output:
{"message": "[WSO2-IAM.Spelling] Did you really mean 'html'?", "location": {"path": "en/includes/guides/branding/add-custom-layouts.md", "range": {"start": {"line": 186, "column": 40}}}, "severity": "WARNING"}

2. Copy the code snippet from the [css file](https://github.com/wso2/docs-is/tree/master/en/identity-server/{{is_version}}/docs/assets/code-samples/style.css){target="_blank"} into the `styles.css` file.

Expand Down Expand Up @@ -199,7 +211,7 @@
Select **Custom** layout as the **Login Layout** and click **Save & Publish** to apply the branding configurations.

!!! tip
If the server stops working after the changes are added, restart the server before verifying the changes.
If the server stops working after the changes are added, restart the server before verifying the changes.

Check warning on line 214 in en/includes/guides/branding/add-custom-layouts.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[write-good.E-Prime] Try to avoid using 'are'.

Raw Output:
{"message": "[write-good.E-Prime] Try to avoid using 'are'.", "location": {"path": "en/includes/guides/branding/add-custom-layouts.md", "range": {"start": {"line": 214, "column": 54}}}, "severity": "INFO"}

Check warning on line 214 in en/includes/guides/branding/add-custom-layouts.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[Microsoft.Passive] 'are added' looks like passive voice.

Raw Output:
{"message": "[Microsoft.Passive] 'are added' looks like passive voice.", "location": {"path": "en/includes/guides/branding/add-custom-layouts.md", "range": {"start": {"line": 214, "column": 54}}}, "severity": "INFO"}

Check warning on line 214 in en/includes/guides/branding/add-custom-layouts.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[write-good.Passive] 'are added' may be passive voice. Use active voice if you can.

Raw Output:
{"message": "[write-good.Passive] 'are added' may be passive voice. Use active voice if you can.", "location": {"path": "en/includes/guides/branding/add-custom-layouts.md", "range": {"start": {"line": 214, "column": 54}}}, "severity": "WARNING"}

5. Refresh the browser and check out the added custom layout.

Expand All @@ -208,6 +220,6 @@

Use the following best practices when creating a custom layout:

- Add a prefix for the new CSS classes so that the newly added classes will not conflict with existing classes.

Check failure on line 223 in en/includes/guides/branding/add-custom-layouts.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'won't' instead of 'will not'.

Raw Output:
{"message": "[Microsoft.Contractions] Use 'won't' instead of 'will not'.", "location": {"path": "en/includes/guides/branding/add-custom-layouts.md", "range": {"start": {"line": 223, "column": 72}}}, "severity": "ERROR"}

- In your development environment, be sure to add the `cache="false"` flag as a parameter in the `<layout:main>` tag of all pages that require testing with the custom layout. With this flag in place, the layouts will compile at runtime eliminating the need to manually recompile layouts. Remember to remove this flag in the production environment.
- In your development environment, be sure to add the `cache="false"` flag as a parameter in the `<layout:main>` tag of all pages that require testing with the custom layout. With this flag in place, the layouts will compile at runtime eliminating the need to manually recompile layouts. Remember to remove this flag in the production environment.

Check warning on line 225 in en/includes/guides/branding/add-custom-layouts.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[write-good.E-Prime] Try to avoid using 'be'.

Raw Output:
{"message": "[write-good.E-Prime] Try to avoid using 'be'.", "location": {"path": "en/includes/guides/branding/add-custom-layouts.md", "range": {"start": {"line": 225, "column": 36}}}, "severity": "INFO"}
Loading