FAQ Documentation

docs/faq.md

@@ -0,0 +1,69 @@
+<!-- meta
+{
+  "node": {
+    "label": "FAQ",
+    "category": {
+      "label": "Basics"
+    },
+    "metaData": {
+      "categoryPosition": 1,
+      "position": 3
+    }
+  }
+}
+meta -->
+
+# Frequently asked questions about Luigi
+
+<!-- accordion:start -->
+
+### What is Luigi?
+
+Luigi is a micro frontend framework that helps you build modularizable, extensible, scalable and consistent UIs and web applications (for administrators and business users).
+
+### What are micro frontends?
+
+The term "micro frontends" extends the concepts of micro services to the frontend. It's an architectural style where big frontend monoliths are decomposed into smaller and simpler chunks to be developed, tested, deployed and maintained independently and rapidly (by many distributed teams), while still appearing to the customer as a one cohesive product.
+
+### Does Luigi deliver micro frontends?
+
+No, Luigi itself does not deliver any micro frontends. It is a framework that helps you develop micro frontends and connect them to web applications.
+
+### Where can I download Luigi?
+
+The Luigi project can be found on [GitHub](https://github.com/SAP/luigi). Depending on the UI framework you use, there are different setups for Luigi. You can find more information here: [application setup](application-setup.md).
+
+
+
+### The distributed development possibilities seem like a big advantage; is that just an additional benefit from using Luigi, or was that a main factor behind it?
+
+Development scalability was one of the main goals right from the beginning. There is a nice article on [martinfowler.com](https://martinfowler.com/articles/micro-frontends.html) explaining the benefits of a micro frontend architecture in general. All the disadvantages of the iframe approach mentioned in the article are solved with Luigi. 
+
+### One of the potential issues with a micro frontend architecture is styling. You suggest to use the CSS elements of Fundamentals to solve that issue. Is that correct?
+
+It is crucial that all micro frontends in a solution follow the same design guidelines. Luigi's default UI styling is based on [Fundamentals](https://sap.github.io/fundamental-styles/) but it can be customised. If you don’t want to use Fundamentals, but Bootstrap, Material, or something else instead, you need to re-style the Luigi view components according to your design guidelines or replace them with your own components completely.
+
+
+
+
+
+### Luigi claims to be ‘technology agnostic’. Are you referring to the UI framework that can be used, or to some other technology?
+
+The main point is that you can choose any base frontend technology you prefer, such as UI5, Angular, React, or Vue. You can even mix them in one solution. One micro frontend can use UI5, while another is written in Angular and Fundamentals. The only thing that matters is that HTML/JavaScript/CSS resources are provided and served via HTTPS in the end. The fact that a micro frontend is its own web application also means that you have full freedom regarding your development toolchain and CI/CD solutions, and the web server you want to use (such as Nginx, Apache, Tomcat, or Github Pages).
+
+Last but not least, "technology agnostic" also means that there are no conflicts regarding any additional libraries you use, such as D3.js, Chart.js, or others. You can also avoid conflicts between different versions of the same library. Imagine a monolithic web application where a lot of teams are contributing and there has been a decision that Chart.js is the data visualization framework of choice, and then there is a need for updating the version, which potentially has breaking changes. In that case, all the teams have to be approached and asked if they use it, if their code is affected by the version update and, if so, when they can deliver the necessary changes. With Luigi, you don‘t have this management overhead at all.
+
+### Are there any equivalents of Luigi?
+
+Yes, there are several. Here are some of the most popular: [Mosaic](https://www.mosaic9.org/), [Single-spa](https://github.com/CanopyTax/single-spa), [OpenComponents](https://opencomponents.github.io/), [Piral](https://www.piral.io). Note that they are not 100% equivalents of Luigi!
+
+<!--
+### In what way is Luigi different from these mentioned framework/products?
+
+TBD
+-->
+
+### Is Luigi already being used within any products, or is it still too new?
+
+Yes, it is already being used in production and close-to-production within SAP. For example in Kyma, SAP C/4HANA Cockpit, Context Driven Services, Konduit and Varkes. Outside of SAP, SAAS AG (partner) uses Luigi. Additionally, there are some POCs going on and we're supporting a few other customers and partners who want to start using Luigi soon.
+<!-- accordion:end -->

docs/luigi-client-api.md

@@ -1,7 +1,7 @@
 <!-- meta
 {
   "node": {
-    "label": "API",
+    "label": "API Reference",
     "category": {
       "label": "Luigi Client"
     },

docs/luigi-core-api.md

@@ -1,7 +1,7 @@
 <!-- meta
 {
   "node": {
-    "label": "API",
+    "label": "API Reference",
     "category": {
       "label": "Luigi Core"
     },

website/docs/public/index.html

@@ -1,12 +1,13 @@
 <!DOCTYPE html>
 <html>
   <head>
-    <title>Luigi Core</title>
+    <title>Documentation - Luigi - The Enterprise-Ready Micro Frontend Framework</title>
     <meta charset="UTF-8">
     <meta
       name="viewport"
       content="width=device-width, user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1"
     />
+    <link rel="icon" type="image/png" sizes="32x32" href="https://www.luigi-project.io/assets/img/favicon.png" />
     <link rel="stylesheet" href="/luigi-core/luigi.css" />
     <link rel="stylesheet" href="/coreStyles.css" />
   </head>

website/docs/scripts/markdown.unified-preview.js

@@ -7,9 +7,10 @@ const filesToProcess = [
   // 'link.md',
   // 'codeblocks.md',
   // 'custom-attributes.md',
-  'frontmatter-3.md',
-  'frontmatter-2.md',
-  'frontmatter.md'
+  'custom-wrappers.md',
+  // 'frontmatter-3.md',
+  // 'frontmatter-2.md',
+  // 'frontmatter.md'
 ];
 
 filesToProcess.forEach(async (name) => {

website/docs/scripts/mocks/custom-wrappers.md

@@ -0,0 +1,38 @@
+# Frequently asked questions
+
+Here we have some answers to your questions
+
+<!-- accordion:start -->
+
+### This is the Accordion Headline
+
+This is the text
+This is the text
+This is the text
+This is the text
+
+```
+Sample code
+```
+### Whats next?
+
+Everything fine!
+
+<!-- accordion:end -->
+
+And now an accordion with all items openend
+
+
+<!-- accordion:start defaultState:active -->
+
+### Another Section
+
+This is the text
+This is the text
+
+### Another Section
+
+This is the text
+This is the text
+
+<!-- accordion:end -->

website/docs/src/client-js/accordion.js

@@ -0,0 +1,8 @@
+export class Accordion {
+  init() {
+    window.accordionToggle = (event, element) => {
+      event.preventDefault();
+      element.parentNode.classList.toggle('active');
+    };
+  }
+}

website/docs/src/client-js/internal-links.js

@@ -8,16 +8,18 @@ export class InternalLinksHandler {
 
       // modify internal links to be valid links for users and still make sapper happy 
       // since leaving them "wrong" (as local iframe links) in the first place
-      const links = document.querySelectorAll('a[data-linktype]');
-      if (links) {
-        links.forEach((link, index) => {
-          if (link.getAttribute('data-linktype') === 'internal') {
-            const url = new URL(link.href);
-            let newHref = ctx.coreBaseUrl + url.pathname.replace('.md', '').replace('/docu-microfrontend', '') + url.hash.toLowerCase();
-            link.setAttribute('href', newHref);
-          }
-        });
-      }
+      let intvCount = 0;
+      const intv = setInterval(() => {
+        const links = document.querySelectorAll('a[data-linktype]');
+        intvCount++;
+        if (links.length) {
+          this.prepareLinks(ctx, links);
+        }
+        if (links.length || intvCount >= 20) {
+          clearInterval(intv);
+        }
+      }, 150);
+
 
       // register click handler
       window.navigateInternal = (evt, elem) => {
@@ -38,4 +40,14 @@ export class InternalLinksHandler {
       }
     });
   }
+
+  prepareLinks(ctx, links) {
+    links.forEach((link) => {
+      if (link.getAttribute('data-linktype') === 'internal') {
+        const url = new URL(link.href);
+        let newHref = ctx.coreBaseUrl + url.pathname.replace('.md', '').replace('/docu-microfrontend', '') + url.hash.toLowerCase();
+        link.setAttribute('href', newHref);
+      }
+    });
+  }
 }

website/docs/src/client.js

@@ -3,13 +3,15 @@ import * as sapper from '@sapper/app';
 import { CopyCodeHandler } from './client-js/copy-code';
 import { InternalLinksHandler } from './client-js/internal-links';
 import { ScrollAnchorsHandler } from './client-js/smooth-scroll-anchors';
+import { Accordion } from './client-js/accordion';
 
 sapper.start({
 	target: document.querySelector('#sapper')
 });
 
 new CopyCodeHandler().init();
 new InternalLinksHandler().init();
+new Accordion().init();
 
 new ScrollAnchorsHandler().init();
 

website/docs/src/luigi-config/extended/settings.js

@@ -7,7 +7,7 @@ class Settings {
   };
 
   responsiveNavigation = 'simpleMobileOnly'; // Options: simple | simpleMobileOnly | semiCollapsible
-  sideNavFooterText = 'Copyright 2019.';
+  sideNavFooterText = ' ';
   // hideNavigation = true
   // backdropDisabled = true
 }

website/docs/src/luigi-config/styles/index.scss

@@ -313,18 +313,34 @@ $side-nav-width: 260px;
   .lui-side-nav__footer {
     background-color: $secondary-color;
     color: white;
+    min-height: 58px;
+
+    a {
+      color: white;
+      display: inline-block;
+      margin-right: 20px;
+
+      &:last-child {
+        margin-right: 0;
+      }
+
+      &:hover,
+      &:active {
+        color: $primary-color;
+      }
+    }
 
     .lui-side-nav__footer--text {
       width: 100%;
       color: white;
       font-size: 14px;
       font-weight: 600;
-      text-align: center;
-      padding: 20px;
-      &:before {
-        content: '\00a9';
-        margin-right: 5px;
-      }
+      padding: 20px 40px;
+
+      // &:before {
+      //   content: '\00a9';
+      //   margin-right: 5px;
+      // }
     }
   }
 
@@ -402,7 +418,7 @@ $side-nav-width: 260px;
     padding: 30px;
 
     @media screen and (min-width: 1024px) {
-      padding: 93px 40px 0;
+      padding: 50px 40px 0;
     }
   }
 

website/docs/src/routes/_layout.svelte

@@ -11,6 +11,7 @@
 	$light-gray: #e6e6e6;
 	$medium-gray: #cacaca;
 	$powder-blue: #d0d8e2;
+	$ice-blue: #edf2f7;
 
 	$side-nav-width: 320px;
 
@@ -33,9 +34,10 @@
 
 			padding: 30px;
 			font-size: 16px;
+			max-width: 1500px;
 
 			@media screen and (min-width: (1024px - $side-nav-width)) {
-				padding: 95px 80px;
+				padding: 50px 80px;
 			}
 		}
 
@@ -401,6 +403,72 @@
 			border-radius: 3px;
 			font-size: 14px;
 		}
+
+		.accordion-container {
+
+			margin: 30px 0;
+
+			@media screen and (min-width: (1024px - $side-nav-width)) {
+				margin: 50px 0;
+			}
+
+			.accordion-item {
+
+				margin-bottom: 12px;
+				border: 1px solid $powder-blue;
+				position: relative;
+
+				&:after {
+					display: block;
+					position: absolute;
+					top: 18px;
+					right: 21px;
+					content: '+';
+					color: $primary-color;
+					font-size: 28px;
+				}
+
+				&.active {
+					.accordion-item-content {
+						display: block;
+					}
+
+					.accordion-item-title {
+						background-color: $ice-blue;
+					}
+
+					&:after {
+						top: 16px;
+						content: '\2013';
+					}
+				}
+			}
+
+			.accordion-item-title {
+				padding: 18px 80px 18px 20px;
+				cursor: pointer;
+
+				h3 {
+					font-size: 16px;
+					line-height: 28px;
+					margin: 0;
+					font-weight: 600;
+				}
+			}
+
+			.accordion-item-content {
+				display: none;
+				margin: 0;
+				padding: 18px 20px;
+
+				p {
+
+					&:last-child {
+						margin-bottom: 0;
+					}
+				}
+			}
+		}
 	}
 </style>
 

website/docs/src/services/markdown.service.js

@@ -10,6 +10,7 @@ import frontmatter from 'remark-frontmatter';
 import luigiLinkParser from '../unified-plugins/rehype-luigi-linkparser';
 import addCopyToClipboard from '../unified-plugins/rehype-copy-to-clipboard';
 import addCustomAttributes from '../unified-plugins/rehype-add-custom-attributes';
+import wrapAccordion from '../unified-plugins/rehype-accordion';
 import luigiNavigationBuilder from '../unified-plugins/remark-generate-luigi-navigation';
 
 // import highlight from 'rehype-highlight' // syntax highlight code blocks with lowlight: https://github.com/wooorm/lowlight
@@ -27,10 +28,11 @@ class MarkdownService {
         .use(remark2rehype, {allowDangerousHTML: true})
         .use(raw)
         .use(addCustomAttributes)
+        .use(wrapAccordion, { questionTagName: 'h3' })
         .use(luigiLinkParser, data)
-        .use(section)
         .use(addIdsToHeadings)
         .use(addCopyToClipboard)
+        .use(section) // section should be the last one
         .use(format)
         .use(html)
         .process(String(value), function (err, file) {