Merge pull request #4840 from jeradrutnam/master

Add new template for complete guides + Add config to select top nav items

en/asgardeo/docs/complete-guides/react/create-a-react-application.md

@@ -0,0 +1,42 @@
+---
+template: templates/complete-guide.html
+heading: Create a React application
+read_time: 2 min
+---
+
+If you want to try out with a sample application without going through this guide, you can use the sample React app [here](https://github.com/asgardeo/asgardeo-auth-react-sdk/tree/main/samples/asgardeo-react-app) with the necessary boilerplate. 
+
+For this guide, you will be creating a simple React app using [Vite](https://vitejs.dev/), a modern, fast and lightweight tool that helps you quickly set up and develop modern JavaScript applications. Open a terminal, change directory to where you want to initialize the project, and run the following command to create your first React sample application.
+
+!!! note "Note"
+
+    You need to have installed [Node.js](https://nodejs.org/en/download/package-manager) v18+ and npm (which comes inbuilt with Node) to run this sample. Although Node.js is primarily a server-side language,it needs to have been installed to manage dependencies and run scripts for our project.
+
+```bash
+npm create vite@latest react-authentication-demo –- --template react
+```
+
+Running this command will create a folder with a ready-to-run boilerplate React project, with a development server to run the project and instantly reload changes to the project in your browser without manual refresh.
+
+Once the application is created, install the dependencies using the following command.
+
+```bash
+cd react-authentication-demo
+npm install
+```
+
+Then run the sample in the development mode. This allows you to see real-time updates and debug the application as you make changes.
+
+```bash
+npm run dev
+```
+
+Confirm that the dev server is up and running by verifying the following output in the terminal.
+
+![Dev server is runnig]({{base_path}}/complete-guides/react/assets/img/image13.png){: width="600" style="display: block; margin: 0;"}
+
+Navigate to http://localhost:5173 and you should see the sample application working in the browser.
+
+![Navigate to localhost]({{base_path}}/complete-guides/react/assets/img/image6.png){: width="600" style="display: block; margin: 0;"}
+
+At this point, you have a simple yet fully functional React app. In the next step, let’s try to integrate an OIDC SDK with the app. 

en/asgardeo/docs/complete-guides/react/introduction.md

@@ -0,0 +1,47 @@
+---
+template: templates/complete-guide.html
+heading: Introduction
+read_time: 2 mins
+---
+
+## Why do you need user login 
+
+React is a widely used JavaScript library designed for creating dynamic single-page applications (SPAs). It enables developers to build responsive interfaces by breaking down complex UIs into reusable components. Unlike traditional UI technologies, React updates specific parts of the page without re-rendering the entire page, thanks to its virtual DOM. This capability makes React popular for developing SPAs.
+
+Implementing login functionality in your React app is essential for managing user access, personalizing user experiences, and securing the app. It enhances user experience, protects user data, boosts engagement, and helps ensure regulatory compliance.
+
+![Should I worry about adding user login?]({{base_path}}/complete-guides/react/assets/img/image4.png){: width="600" style="display: block; margin: 0;"}
+
+
+## D.I.Y or use an Identity Provider (IdP) 
+
+It’s perfectly okay to implement login for your React app by yourself. As a starting step, you may add a login page and store usernames and passwords in a database . However, this approach will not be scalable in the long run because:
+
+1. User login becomes complex over time with the need for features like multi-factor authentication (MFA), adaptive authentication, passwordless login, social login, and Single Sign-On (SSO).
+2. Account management becomes complex with requirements like password policies, password resets, forgotten usernames, and onboarding from social platforms.
+
+![How should I add user login?]({{base_path}}/complete-guides/react/assets/img/image3.png){: width="600" style="display: block; margin: 0;"}
+
+Fortunately, there are production-grade authentication providers and login SDKs available to simplify these tasks for you. Integrating your app with an identity provider simplifies user login and ensures secure access to resources, offloading complex tasks like credential management and session handling. In this guide, you'll be using Asgardeo as the IdP. If you don’t have Asgardeo you can instantly sign-up for a free account from [here]. Asgardeo offers a generous free tire account that is more than enough during the app development phase.   
+
+## Build secure apps using SDKs 
+
+If you are going down the path of integrating with an Identity Provider (IdP), again you have two options:
+
+1. **Do it yourself (D.I.Y):** You can implement OIDC request-response flows and token processing yourself using a combination of React features and JavaScript. This approach gives you full control over the authentication process but requires a deeper understanding of OIDC protocols and a significant investment of time to ensure secure and reliable implementation.
+2. **Using a React SDK:** Alternatively, you can integrate a production-ready React SDK into your app. This approach simplifies the implementation of login by providing pre-built methods for handling sign-ins, token management, and session control. The SDK manages complex and sensitive processes like token validation and renewal, enhancing security while reducing development time. 
+
+![How should integrate wiuth an IdP?]({{base_path}}/complete-guides/react/assets/img/image2.png){: width="600" style="display: block; margin: 0;"}
+
+This guide will walk you through everything you need to know about securing React applications, including implementing user login in your React app, integrating it with an Identity Provider (IdP) to make the login process simple and secure, and general guidelines to protect your end users. 
+
+Here is the order you are going to follow throughout this guide:
+
+* Register an application in Asgardeo/IS
+* Create a React application
+* Install Asgardeo React SDK
+* Add login and logout  to your app
+* Display logged in user detail
+* Securing routes within the app
+* Accessing protected API from your React app
+* Token management in React app

en/asgardeo/docs/complete-guides/react/prerequisite.md

@@ -0,0 +1,17 @@
+---
+template: templates/complete-guide.html
+heading: Prerequisite
+read_time: 30 secs
+---
+
+## Before you start, ensure you have the following:
+
+* About 60 minutes
+* Asgardeo account
+* Install a JS package manager
+* A favorite text editor or IDE
+
+
+!!! tip "Tip"
+
+    If you want to quickly build a React application, try the React Quick Start guide here. It takes around 15 minutes.

en/asgardeo/docs/complete-guides/react/register-an-application-in-asgardeo-is.md

@@ -0,0 +1,27 @@
+---
+template: templates/complete-guide.html
+heading: Register an application in Asgardeo/IS
+read_time: 2 min
+---
+
+First unless you already have done that, you need to create an organization in Asgardeo and register your application as a single page application.
+
+* Sign up for a free Asgardeo account at wso2.com/asgardeo 
+* Sign into Asgardeo console and navigate to Applications > New Application.
+* Select Single Page Application
+
+![Select Single Page Application]({{base_path}}/complete-guides/react/assets/img/image5.png){: width="600" style="display: block; margin: 0;"}
+
+Complete the wizard popup by providing a suitable name and an authorized redirect URL. 
+
+![Register a new application]({{base_path}}/complete-guides/react/assets/img/image8.png){: width="600" style="display: block; margin: 0;"}
+
+!!! note "Note"
+
+    The authorized redirect URL determines where Asgardeo should send users after they successfully log in. Typically, this will be the web address where your application is hosted. For this guide, we'll use http://localhost:5173, as the sample application will be accessible at this URL.
+
+!!! tip "Hint"
+
+    Use the information available in the Quick Start tab of your app or the Quickstart guide under the React SDK for the AuthProvider config.
+
+![Quick start guide]({{base_path}}/complete-guides/react/assets/img/image9.png){: width="600" style="display: block; margin: 0;"}

en/asgardeo/mkdocs.yml

@@ -33,6 +33,7 @@ extra:
   product: asgardeo
   product_name: *site_name
   nav_list:
+    - Home
     - Get Started
     - Guides
     - Tutorials
@@ -474,6 +475,11 @@ nav:
         - Client-request: references/token-binding/client-request.md
       - Financial-grade API: references/financial-grade-api.md
       - App-native authentication: references/app-native-authentication.md
+  - React Guide:
+    - Intruduction: complete-guides/react/introduction.md
+    - Prerequisite: complete-guides/react/prerequisite.md
+    - Register an application in Asgardeo/IS: complete-guides/react/register-an-application-in-asgardeo-is.md
+    - Create a React application: complete-guides/react/create-a-react-application.md
 
 not_in_nav: |
   /page-not-found.md

en/base.yml

@@ -29,6 +29,8 @@ theme:
     - navigation.indexes
     - navigation.path
     - navigation.top
+    - navigation.footer
+    - navigation.instant.progress
     - content.code.copy
     - content.action.edit
     - content.action.view

en/identity-server/is_common.yml

@@ -35,6 +35,7 @@ extra:
   product: is
   product_name: *site_name
   nav_list:
+    - Home
     - Get Started
     - Guides
     - Setup

en/theme/material/assets/css/complete-guide.css

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) 2024, WSO2 LLC. (https://www.wso2.com).
+ *
+ * WSO2 LLC. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+.md-sidebar--secondary {
+    display: none !important;
+}
+
+.md-nav__item {
+    padding-right: .6rem;
+    display: flex;
+    flex-direction: row;
+    vertical-align: top;
+    margin-bottom: 10px;
+}
+
+.guide-page-number {
+    display: inline-block;
+    margin-top: 1px;
+    margin-right: 10px;
+    background: var(--md-default-fg-color);
+    color: var(--md-default-bg-color);
+    font-size: 12px;
+    border-radius: 50%;
+    height: 22px;
+    width: 22px;
+    flex: 0 0 22px;
+    line-height: 22px;
+    text-align: center;
+}
+
+.md-nav__link {
+    display: inline-block;
+    margin-top: 0 !important;
+}

en/theme/material/assets/css/theme.css

@@ -373,6 +373,20 @@
     display: none;
 }
 
+.md-nav__link-read_time {
+    font-size: 10px;
+    color: var(--md-default-fg-color--light);;
+    white-space: nowrap;
+    word-break: keep-all;
+    font-style: italic;
+}
+
+.md-typeset h1 > span {
+    font-size: 14px;
+    font-style: italic;
+    color: var(--md-default-fg-color--light);
+  }
+
 /* Media query breakpoints
 
     $base_px: 16px;