feat(gh-pages): the ability to include markdown into demo pages (#368)

Co-authored-by: Anna <[email protected]>

.eleventy.js

@@ -1,12 +1,21 @@
-const { isDev } = require('./pages/views/_data/env');
 const htmlmin = require('html-minifier');
 
+const { isDev } = require('./pages/views/_data/env');
+const { markdown } = require('./pages/views/_data/markdown');
+const { MDRenderer } = require('./pages/views/_data/md-render');
+
 module.exports = (config) => {
+  config.addWatchTarget('src/**/*.md');
+
   config.addPassthroughCopy({
     'pages/static/assets': 'assets',
     'pages/static/tools': '.',
   });
 
+  config.setLibrary('md', markdown);
+
+  config.addNunjucksAsyncShortcode('mdRender', MDRenderer.render);
+
   config.addFilter('sortByName', (values) => {
     if (!values || !Array.isArray(values)) {
       console.error(`Unexpected values in 'sortByName' filter: ${values}`);
@@ -26,15 +35,14 @@ module.exports = (config) => {
 
   config.addTransform('htmlmin', function (content, outputPath) {
     if (outputPath && outputPath.endsWith('.html') && !isDev) {
-      let minified = htmlmin.minify(content, {
+      return htmlmin.minify(content, {
         useShortDoctype: true,
         removeComments: true,
         collapseWhitespace: true,
         keepClosingSlash: true,
         minifyJS: true,
         minifyCSS: true,
       });
-      return minified;
     }
     return content;
   });

jest.config.js

@@ -1,6 +1,4 @@
 module.exports = {
-  // runner: 'jest-electron/runner',
-  // testEnvironment: 'jest-electron/environment',
   testEnvironment: 'jsdom',
   preset: 'ts-jest',
   roots: ['src/modules'],

package.json

@@ -98,6 +98,7 @@
     "eslint-plugin-import": "^2.23.4",
     "eslint-plugin-sonarjs": "^0.9.1",
     "foreach-cli": "^1.8.1",
+    "highlight.js": "^11.1.0",
     "html-minifier": "^4.0.0",
     "husky": "^7.0.1",
     "intersection-observer": "^0.12.0",

pages/src/common/markdown.less

@@ -0,0 +1,5 @@
+.markdown-container {
+  & ul {
+  padding-left: 1.5rem;
+  }
+}

pages/src/common/page.less

@@ -2,9 +2,10 @@
   margin: 0;
   padding: 0;
   box-sizing: border-box;
-}
-*:focus {
-  outline: 1px dotted gray;
+
+  &:focus {
+    outline: 1px dotted gray;
+  }
 }
 
 .footer {
@@ -22,7 +23,6 @@
 
 body {
   display: flex;
-  //min-width: 650px;
   min-height: 100vh;
   color: rgba(22, 0, 27, 0.9);
   flex-direction: column;

pages/src/localdev.less

@@ -1,6 +1,9 @@
 @import (inline) "./libs/bootstrap.css";
+@import "./common/markdown.less";
 @import "./common/page.less";
 @import "./header/header.less";
 
 @import "../../src/modules/all.less";
 @import "../../src/modules/draft/all.less";
+
+@import (inline) "../../node_modules/highlight.js/styles/github.css";

pages/views/_data/markdown.js

@@ -0,0 +1,16 @@
+const hljs = require('highlight.js');
+const markdownLib = require('markdown-it');
+
+const markdown = markdownLib({
+  html: true,
+  highlight: function (str, lang) {
+    if (lang && hljs.getLanguage(lang)) {
+      try {
+        return hljs.highlight(str, { language: lang }).value;
+      } catch { }
+    }
+    return '';
+  }
+});
+
+module.exports = { markdown };

pages/views/_data/md-render.js

@@ -0,0 +1,55 @@
+const path = require('path');
+const fsAsync = require('fs').promises;
+const { JSDOM } = require('jsdom');
+
+const { markdown } = require('./markdown');
+
+const fileCache = new Map();
+
+const parseFile = async (filePath) => {
+  const absolutePath = path.resolve(__dirname, '../../../', filePath);
+
+  if (fileCache.has(absolutePath)) return fileCache.get(absolutePath);
+
+  const data = await fsAsync.readFile(absolutePath);
+  const content = data.toString();
+  const renderedContent = markdown.render(content);
+
+  fileCache.set(absolutePath, renderedContent);
+  return renderedContent;
+};
+
+// <p><a name></a></p>
+const unwrapAnchor = (anchor) => anchor && anchor.matches(':only-child') ? anchor.parentElement : anchor;
+
+class MDRenderer {
+  static wrapContent(content) {
+    return `<div class="markdown-container">${content}</div>`;
+  }
+
+  static async render(filePath, startSel, endSel) {
+    try {
+      const content = await parseFile(filePath);
+
+      if (!startSel) return MDRenderer.wrapContent(content);
+
+      const { window } = new JSDOM(content);
+      const startAnchor = window.document.querySelector(`a[name='${startSel}']`);
+      const endAnchor = window.document.querySelector(`a[name='${endSel}']`);
+
+      let node = unwrapAnchor(startAnchor);
+      let endNode = unwrapAnchor(endAnchor);
+      let partContent = '';
+
+      for (node = node.nextSibling; !!node && node !== endNode; node = node.nextSibling) {
+        partContent += node.outerHTML || node.textContent;
+      }
+
+      return MDRenderer.wrapContent(partContent);
+    } catch (e) {
+      return `Rendering error: ${e}`;
+    }
+  }
+}
+
+module.exports = { MDRenderer };

pages/views/_includes/header-menu.njk

@@ -1,14 +1,14 @@
 {% macro menu(title, collection) %}
   <esl-trigger class="hd-dropdown-trigger" track-hover target="::next">
-    <button class="btn btn-link hd-dropdown-btn hd-dropdown-arrow {{ 'text-info' if collection in page.url}}">
+    <button class="btn btn-link hd-dropdown-btn hd-dropdown-arrow {{ 'text-info' if collection in page.url }}">
       {{ title }}
     </button>
   </esl-trigger>
   <esl-panel class="hd-dropdown-content" default-params="{hideDelay: 250}" fallback-duration="500">
     {% if collections[collection] %}
       <ul class="hd-dropdown-list">
         {% for item in collections[collection] | sortByName %}
-          {% set isActive = page.url == item.url %}
+          {% set isActive = page.url === item.url %}
           <li class="nav-item hd-dropdown-item {{ 'active' if isActive }}" {% if isActive %}aria-current="page"{% endif %}>
             <a class="hd-dropdown-link" href="{{ item.url | url }}">{{ item.data.name }}</a>
           </li>

pages/views/_includes/header.njk

@@ -1,20 +1,20 @@
 <nav class="navbar navbar-expand-lg navbar-dark bg-dark esl-demo-header">
   <div class="container flex-column flex-lg-row align-items-stretch align-items-lg-center">
     <a class="navbar-brand logo-light mr-5" href="{{ '/' | url }}">
-      {% include "img/logo.svg" %}
+      {% include 'pages/static/assets/logo.svg' %}
       <span class="ml-2">Exadel Smart Library</span>
     </a>
     {% from 'header-menu.njk' import menu with context %}
     <ul class="navbar-nav flex-grow-1 flex-sm-row">
       <li class="nav-item hd-dropdown">
-        {{ menu ("Components", "basic") }}
+        {{ menu ('Components', 'basic') }}
       </li>
       <li class="nav-item hd-dropdown">
-        {{ menu ("Form Components", "forms") }}
+        {{ menu ('Form Components', 'forms') }}
       </li>
       {% if env.isDev %}
         <li class="nav-item hd-dropdown">
-          {{ menu ("Drafts", "drafts") }}
+          {{ menu ('Drafts', 'drafts') }}
         </li>
       {% endif %}
 

pages/views/_layouts/basic.njk

@@ -1,4 +1,4 @@
-{% extends "./html5.njk" %}
+{% extends './html5.njk' %}
 {% set scrollbar = true %}
 
 {% block head %}
@@ -16,7 +16,7 @@
   </script>
 
   <link rel="icon" type="image/png" href="{{ '/assets/logo-64x64.png' | url }}" />
-  <link type="text/css" rel="stylesheet" href="{{ '/bundles/localdev.css' | url }}" />
+  <link rel="stylesheet" type="text/css" href="{{ '/bundles/localdev.css' | url }}" />
 
   {% block extra_head %}{% endblock %}
 {% endblock %}

pages/views/basic/esl-accordion.njk

@@ -7,6 +7,8 @@ tags: basic
 ---
 {% import 'lorem.njk' as lorem %}
 
+{% mdRender 'src/modules/esl-trigger/README.md', 'intro' %}
+
 <section class="row">
   <style>
     .card-header[active] {

pages/views/basic/esl-alert.njk

@@ -6,6 +6,8 @@ containerCls: container
 tags: basic
 ---
 
+{% mdRender 'src/modules/esl-alert/README.md', 'intro' %}
+
 <section class="row">
   <div class="col-12">
     <h3 class="text-center">Triggers</h3>

pages/views/basic/esl-image.njk

@@ -7,6 +7,8 @@ tags: basic
 ---
 {% set imageSrcBase = '/assets/' | url %}
 
+{% mdRender 'src/modules/esl-image/README.md', 'intro' %}
+
 <section class="row">
   <div class="col-12">
     <h3 class="text-center">Mods</h3>

pages/views/basic/esl-media.njk

@@ -5,6 +5,10 @@ name: Esl Media
 tags: basic
 ---
 
+<div class="content container">
+  {% mdRender 'src/modules/esl-media/README.md', 'intro' %}
+</div>
+
 <div class="description">
   <p>ESL Media - is a esl container that gives you the same API for different providers under the hood
     along with helpers like <em>lazy loading</em>, <em>activate query</em>, <em>picture cropping</em>.</p>
@@ -149,7 +153,8 @@ tags: basic
     </div>
   </section>
 
-  <section class="col-12" data-demo="7">
+  {# Hide it temporary before playground integration #}
+  <section class="col-12" data-demo="7" hidden>
     <h3 class="text-center">Load condition</h3>
     <p class="text-center">Load condition feature allows us to define using ESLQuery condition when the video
       source should be loaded.</p>

pages/views/basic/esl-scrollbar.njk

@@ -6,6 +6,10 @@ tags: basic
 ---
 {% import 'lorem.njk' as lorem %}
 
+<div class="content container">
+  {% mdRender 'src/modules/esl-scrollbar/README.md', 'intro' %}
+</div>
+
 <section class="row">
   <style>
     .test-popup {

pages/views/basic/esl-tab.njk

@@ -7,6 +7,8 @@ tags: basic
 ---
 {% import 'lorem.njk' as lorem %}
 
+{% mdRender 'src/modules/esl-tab/README.md', 'intro' %}
+
 <section class="row">
   <style>
     .accordion-trigger {

pages/views/basic/esl-toggleable.njk

@@ -6,6 +6,8 @@ containerCls: container
 tags: basic
 ---
 
+{% mdRender 'src/modules/esl-toggleable/README.md', 'intro' %}
+
 <section class="row">
   <div class="col-12">
     <h4>Click event</h4>

pages/views/forms/esl-select-list.njk

@@ -6,6 +6,8 @@ containerCls: container
 tags: forms
 ---
 
+{% mdRender 'src/modules/esl-forms/esl-select-list/README.md', 'intro' %}
+
 <section class="row">
   <div class="col-12">
     <style>

pages/views/forms/esl-select.njk

@@ -6,6 +6,8 @@ containerCls: container
 tags: forms
 ---
 
+{% mdRender 'src/modules/esl-forms/esl-select/README.md', 'intro' %}
+
 <section class="row">
   <div class="col-12">
     <style>

pages/views/index.njk

@@ -6,7 +6,7 @@ ui_playground: github.com/exadel-inc/ui-playground
 ---
 
 <div class="d-flex flex-column flex-md-row align-items-center">
-  <div class="brand-section logo-primary mr-2">{% include "img/logo.svg" %}</div>
+  <div class="brand-section logo-primary mr-2">{% include 'pages/static/assets/logo.svg' %}</div>
   <p class="m-0 lead description">
     Exadel Smart Library (<strong>ESL</strong>) is a web components based library that gives you a set of <strong>lightweight</strong>
     and <strong>flexible</strong> custom elements to easily create basic UX modules and make your websites super fast.

src/modules/esl-alert/README.md

@@ -1,14 +1,18 @@
-# [ESL](../../../README.md) Alert
+# [ESL](../../../) Alert
 
 Version: *1.0.0*
 
 Authors: *Julia Murashko*
 
+<a name="intro"></a>
+
 ESLAlert is a component to show small notifications on your pages. ESLAlert can have multiple instances on the page.
 
 ---
 
-##Usage
+<a name="usage"></a>
+
+## Usage
 
 First, use the common approach to register component: `ESLAlert.register()`.
 Then you can attach `<esl-alert>` component to the expected place in the document or initialize it globally by using `ESLAlert.init` shortcut.
@@ -30,6 +34,8 @@ Use CustomEvent `details` to customize alert. Alert `details` accepts the follow
 
 If one of `esl-alert`s catches the activation event it will prevent its propagation to parent elements.
 
+<a name="example"></a>
+
 ## Example
 ```html
 <body>

src/modules/esl-forms/esl-select-list/README.md

@@ -1,9 +1,11 @@
-# [ESL](../../../../README.md) Select List
+# [ESL](../../../../) Select List
 
 Version: *1.0.0*
 
 Authors: *Alexey Stsefanovich (ala'n)*
 
+<a name="intro"></a>
+
 ESLSelectList is a component to show selectable list of items. Decorates native HTMLSelectElement
 ESLSelectList is HTML5 form compatible. Uses HTMLSelectElement as a data model.