Merge branch 'master' of https://github.com/IgniteUI/igniteui-docfx-t…

…emplate into dependency-updates

.github/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+## In this topic
+ ### 1. [Manual testing of the docfx-template](#manual-testing)
+ ### 2. [Adding responsive containers](#responsive-containers)
+
+
+## <a name='#manual-testing'>Test Plan:</a>
+
+1. Scroll down the whole page and observe the TOC on the left and side-bar on the right - Scrollbars should appear and all list items should be visible/scrollable.
+2. Observe the right side-bar, click any list item and check if the relevant header part of the topic content is positioned at the top most position.
+3. Check that all code-views are loaded correctly
+    a. Live-editing buttons should work
+    b. Full screen button
+    c. Code tabs should be present
+4. Open a topic that has more than one sample - the first one should be loaded instantly, the latter should be lazy loaded when reaches through page scrolling.
+5. Check if the topic has a CTA banner loaded at the end of the first H2 element.
+6. Test everything with Firefox, Edge and IE11 (live-editing buttons should not be present, and the Theming widget should be replaced by only two buttons for light and dark theme).
+7. Execute `npm run build-staging` and host the Docfx application under IIS (angular-samples should not be running)
+
+
+**Notes:** 
+- npm link the docfx-template to docfx, run angular-samples and [igniteui-theming-widget-api](https://infragistics.visualstudio.com/Ignite%20UI%20Theming%20Tools/_git/igniteui-theming-widget-api)
+- both regular `app` and `app-lob` should be tested
+
+
+## <a name='#responsive-containers'>Responsive containers:</a>
+To add  a single responsive embedded video use the following markup:
+```HTML
+    <section class="video-container">
+        <div class="video-container__item">
+            <iframe src=""></iframe>
+        </div>
+    </section>
+```
+
+To add a single responsive embedded video with a title use the following markup:
+```HTML
+    <section class="video-container">
+        <div>
+            <div class="video-container__item">
+                <iframe src=""></iframe>
+            </div>
+            <p>Video 1</p>
+        </div>
+    </section>
+```
+
+To add multiple responsive embedded videos use the following markup:
+```HTML
+    <section class="video-container">
+        <div>
+            <div class="video-container__item">
+                <iframe src=""></iframe>
+            </div>
+            <p>Video 1</p>
+        </div>
+        <div>
+            <div class="video-container__item">
+                <iframe src=""></iframe>
+            </div>
+            <p>Video 2</p>
+        </div>
+    </section>
+```
+
+If you want to change the aspect ratio of a video or set of videos you can do it by changing the --ratio variable, keep in mind that the value should be in %.
+
+Change the ratio for multiple videos
+```HTML
+    <section class="video-container" style="--ratio: 55%">
+        <div class="video-container__item">
+            <iframe src=""></iframe>
+        </div>
+    </section>
+```
+
+Change the ratio for single video.
+```HTML
+    <section class="video-container">
+        <div class="video-container__item" style="--ratio: 40%">
+            <iframe src=""></iframe>
+        </div>
+    </section>
+```

README.md

@@ -3,6 +3,8 @@
 # Ignite UI DocFX Template
 This is a [DocFX](https://github.com/dotnet/docfx) template which is used for [Ignite UI](https://github.com/igniteui) documentation websites.
 
+## Contributing
+Check out the [Contributing page](.github/CONTRIBUTING.md) for more.
 
 ## Setup
 To setup the project run:
@@ -11,36 +13,70 @@ To setup the project run:
 npm install
 ```
 
-## Bundling and minification
-We provide bundling and minification for JS and CSS files in the template. To run bundling and minification execute:
+To build the project
 
 ```
-npm run bundle-and-minify
+npm run build
 ```
 
-To run the bundling and minification watcher execute:
-
+To run the template in dev mode:
 
 ```
-npm run bundle-and-minify:watch
+npm run build:dev
 ```
+## Link and Debug
+
+In order to run the template locally, after it is build, it should be linked to the repo you want to use it.
 
-### Debugging
-To disable minification for debugging purposes run:
+Go to __dist/__ folder of the template and run:
 
 ```
-npm run bundle-and-minify -- --debugMode=true
+npm link
 ```
 
-or with watcher:
+Then go to the repo which you want to use the template and run this command in the main folder:
 
 ```
-npm run bundle-and-minify:watch -- --debugMode=true
+npm link igniteui-docfx-template
 ```
 
-### Browser Cache Invalidation
-The browser caching invalidation is implemented by appending a query string with the bundle checksum to each bundle URL. Each checksum is a MD5-sum of the content of the bundle. The checksums are generated along with the bundling and minification. They are located in the `bundling.global.json` file which is used as a global metadata by the docFX engine. `bundling.global.json` has an additional `timestamp` variable which is used to invalidate the browser caching for files which are included in the bundling and minification. If you want to generate just the `bundling.global.json`, run:
+After these steps are done, you can run your project and it will automatically use the template.
 
+## Collapsible code snippets
+
+To generate and display collapsible code snippets on documentation websites, follow these steps:
+
+1. Create a \<div> section with the class "fancy-details".
+
+2. Add a \<summary> element to the created \<div> section.
+
+3. Add the summary text representing the code snippet header to the \<summary> element.
+
+4.  Add a \<code> element to the created \<div> section.
+
+5. Add the code snippet to the \<code> element.
+
+6. Example:
 ```
-npm run generate-bundling-global-metadata
-```
+<div class="fancy-details">
+    <summary>Example of a successful response body: </summary>
+    <code>
+        {
+            "id": "{123456}_repo",
+            "modified": "2023-02-03T14:07:34.0000000",
+            "created": "2023-02-03T14:07:34.0000000",
+            "name": "Marketing",
+            "user": {
+                "id": "{123456}_u ",
+                "name": "Teddy Mitkova"
+            },
+            "dashboardSections": [
+                {
+                    "id": "{123456}_f",
+                    "name": "May"
+                }
+            ]
+        }
+    </code>
+</div>
+```

index.js

@@ -27,7 +27,10 @@ exports.buildDocfx = (options = {
     const globalPreconfigs = preconfigs;
     let docfxJsonPath = path.normalize(path.join(getPath(options.projectDir), 'docfx.json'));
     let docfxPreconfigPath = path.normalize(path.join(getPath(options.projectDir), 'environment.json'));
+    let docfxGlobalConfigPath = path.normalize(path.join(getPath(options.projectDir), 'global.json'));
+    let globalConfigs = getEnvironmentVariables(docfxGlobalConfigPath);
     let environmentConfigs = getEnvironmentVariables(docfxPreconfigPath);
+    let applyWarnAsErr = ``;
     environmentConfigs.environment = options.environment || 'development';
 
     globalPreconfigs['variables'] = environmentConfigs[environmentConfigs.environment];
@@ -44,11 +47,30 @@ exports.buildDocfx = (options = {
     );
 
     console.log(`Starting docfx build for: ${getPath(options.projectDir)}`);
-    console.log();
 
-    return spawn("docfx", ["build", `${path.normalize(getPath(docfxJsonPath))}`], { stdio: 'inherit' }).on('close', (err) => {
+    if (globalConfigs._useWarningsAsErrors) {
+        applyWarnAsErr = `--warningsAsErrors`;
+    }
+
+    return spawn("docfx", ["build", applyWarnAsErr, `${path.normalize(getPath(docfxJsonPath))}`], { stdio: 'inherit' }).on('exit', (err) => {
+        if (err === 4294967295) {
+            console.log(`\x1b[31m`, `------------------------------------------------------------------------------------`);
+            console.log(`--------------------------- Bookmark/Hyperlink Errors -----------------------------`);
+            console.log(`-----------------------------------------------------------------------------------`);
+            console.log();
+            console.error(`              Build failed with bookmark warnings marked in yellow above!        `);
+            console.error(`These warnings indicate the specific topic and link that points to the code line.`);
+            console.log();
+            console.log(`-----------------------------------------------------------------------------------`);
+            console.log(`--------------------------- Error Code ` + err + ` ---------------------------------`);
+            console.log(`-----------------------------------------------------------------------------------`, `\x1b[0m`);
+            console.log();
+        } else {
+            console.log('Exiting code with Error: ' + err);
+        }
+    }).on('close', (err) => {
         if (err) {
             console.error(err);
-        }
+        } 
     });
 }