Table of content

nodemon.json

@@ -0,0 +1,13 @@
+{
+  "verbose": true,
+  "ignore": [
+    ".git",
+    "node_modules",
+    "public",
+    "src/frontend"
+  ],
+  "watch": [
+    "**/*"
+  ],
+  "ext": "js,twig"
+}

src/backend/views/layout.twig

@@ -25,6 +25,7 @@
           {% block body %}{% endblock %}
         </div>
       </div>
+      <aside class="docs__aside-right" id="layout-right-column"></aside>
     </div>
     <script src="/dist/main.bundle.js"></script>
     {% if config.yandexMetrikaId is not empty %}

src/frontend/js/app.js

@@ -16,6 +16,7 @@ import ModuleDispatcher from 'module-dispatcher';
 import Writing from './modules/writing';
 import Page from './modules/page';
 import Extensions from './modules/extensions';
+import TableOfContent from "./modules/table-of-content";
 
 /**
  * Main app class

src/frontend/js/modules/page.js

@@ -6,12 +6,13 @@
  * @class Page
  * @classdesc Class for page module
  */
-export default class Writing {
+export default class Page {
   /**
    * Creates base properties
    */
   constructor() {
     this.codeStyler = null;
+    this.tableOfContent = null;
   }
 
   /**
@@ -21,7 +22,8 @@ export default class Writing {
    */
   init(settings = {}, moduleEl) {
     this.codeStyler = this.createCodeStyling();
-  };
+    this.tableOfContent = this.createTableOfContent();
+  }
 
   /**
    * Init code highlighting
@@ -30,7 +32,23 @@ export default class Writing {
     const { default: CodeStyler } = await import(/* webpackChunkName: "code-styling" */ './../classes/codeStyler');
 
     return new CodeStyler({
-      selector: '.block-code__content'
+      selector: '.block-code__content',
+    });
+  }
+
+  /**
+   * Init table of content
+   * @return {Promise<TableOfContent>}
+   */
+  async createTableOfContent() {
+    const { default: TableOfContent } = await import(/* webpackChunkName: "table-of-content" */ './table-of-content');
+
+    return new TableOfContent({
+      tagSelector:
+        'h2.block-header--anchor,' +
+        'h3.block-header--anchor,' +
+        'h4.block-header--anchor',
+      tocWrapperSelector: '#layout-right-column',
     });
-  };
+  }
 }

src/frontend/js/modules/table-of-content.js

@@ -0,0 +1,214 @@
+/**
+ * Generate dynamic table of content
+ */
+export default class TableOfContent {
+  /**
+   * Initialize table of content
+   */
+  constructor({ tagSelector, tocWrapperSelector }) {
+    this.tagSelector = tagSelector || 'h2,h3,h4';
+    this.tocWrapperSelector = tocWrapperSelector;
+
+    this.init();
+  }
+
+  /**
+   * Initialize table of content
+   */
+  init() {
+    this.findTagsOnThePage();
+
+    /**
+     * Check if no tags found
+     */
+    if (this.tags.length === 0) {
+      console.info('Table of content is not needed');
+      return;
+    }
+
+    this.createTableOfContent();
+    this.addTableOfContent();
+    this.initIntersectionObserver();
+  }
+
+  /**
+   * Find all tags on the page
+   */
+  findTagsOnThePage() {
+    this.tags = Array.from(document.querySelectorAll(this.tagSelector));
+  }
+
+  /**
+   * Create table of content
+   *
+   * <section>
+   *   <header>On this page</header>
+   *   <ul>
+   *     <li><a href="#"></a></li>
+   *     ...
+   *   </ul>
+   * </section>
+   */
+  createTableOfContent() {
+    this.tocElement = document.createElement('section');
+    this.tocElement.classList.add('table-of-content__list');
+
+    this.tags.forEach((tag) => {
+      const linkTarget = tag.querySelector('a').getAttribute('href');
+
+      const linkWrapper = document.createElement('li');
+      const linkBlock = document.createElement('a');
+
+      linkBlock.innerText = tag.innerText;
+      linkBlock.href = `${linkTarget}`;
+
+      linkWrapper.classList.add('table-of-content__list-item');
+
+      // additional indent for h3-h6
+      linkWrapper.classList.add(`table-of-content__list-item--${tag.tagName.toLowerCase()}`);
+
+      linkWrapper.appendChild(linkBlock);
+      this.tocElement.appendChild(linkWrapper);
+    });
+  }
+
+  /**
+   * Add table of content to the page
+   */
+  addTableOfContent() {
+    const header = document.createElement('header');
+    const container = document.createElement('section');
+
+    header.innerText = 'On this page';
+    header.classList.add('table-of-content__header');
+    container.appendChild(header);
+
+    container.classList.add('table-of-content');
+    container.appendChild(this.tocElement);
+
+    const tocWrapper = document.querySelector(this.tocWrapperSelector);
+
+    if (!tocWrapper) {
+      throw new Error('Table of content wrapper not found');
+    }
+
+    tocWrapper.appendChild(container);
+  }
+
+  /**
+   * Init intersection observer
+   */
+  initIntersectionObserver() {
+    const options = {
+      rootMargin: '-5% 0 -80%',
+    };
+
+    const callback = (entries) => {
+      entries.forEach((entry) => {
+        const target = entry.target;
+        const targetLink = target.querySelector('a').getAttribute('href');
+
+        /**
+         * Intersection state of block
+         *
+         * @type {boolean}
+         */
+        const isVisible = entry.isIntersecting;
+
+        /**
+         * Calculate scroll direction whith the following logic:
+         *
+         * DOWN: if block top is BELOW (coordinate value is greater) the intersection root top
+         * and block is NOT VISIBLE
+         *
+         * DOWN: if block top is ABOVE (coordinate value is less) the intersection root top
+         * and block is VISIBLE
+         *
+         * UP: if block top is ABOVE (coordinate value is less) the intersection root top
+         * and block is visible
+         *
+         * UP: if block top is BELOW (coordinate value is greater) the intersection root top
+         * and block is NOT VISIBLE
+         *
+         * Therefore we can use XOR operator for
+         * - is block's top is above root's top
+         * - is block visible
+         *
+         * @type {string}
+         */
+        const scrollDirection = ((entry.boundingClientRect.top < entry.rootBounds.top) ^ (entry.isIntersecting)) ? 'down' : 'up';
+
+        /**
+         * If a header becomes VISIBLE on scroll DOWN
+         * then highlight its link
+         *
+         * = moving to the new chapter
+         */
+        if (isVisible && scrollDirection === 'down') {
+          this.setActiveLink(targetLink);
+        }
+
+        /**
+         * If a header becomes NOT VISIBLE on scroll UP
+         * then highlight previous link
+         *
+         * = moving to the previous chapter
+         */
+        if (!isVisible && scrollDirection === 'up') {
+          this.setActiveLink(targetLink, true);
+        }
+      });
+    };
+
+    /**
+     * Create intersection observer
+     */
+    this.observer = new IntersectionObserver(callback, options);
+
+    /**
+     * Add observer to found tags
+     */
+    this.tags.reverse().forEach((tag) => {
+      this.observer.observe(tag);
+    });
+  }
+
+  /**
+   * Highlight link's item with a given href
+   *
+   * @param {string} targetLink - href of the link
+   * @param {boolean} [needHighlightPrevious=false] - need to highlight previous link
+   */
+  setActiveLink(targetLink, needHighlightPrevious = false) {
+    /**
+     * Clear all links
+     */
+    this.tocElement.querySelectorAll('li').forEach((link) => {
+      link.classList.remove('table-of-content__list-item--active');
+    });
+
+    /**
+     * Looking for a target link
+     */
+    const targetElement = this.tocElement.querySelector(`a[href="${targetLink}"]`);
+
+    /**
+     * Getting link's wrapper
+     */
+    let listItem = targetElement.parentNode;
+
+    /**
+     * Change target list item if it is needed
+     */
+    if (needHighlightPrevious) {
+      listItem = listItem.previousSibling;
+    }
+
+    /**
+     * If target list item is found then highlight it
+     */
+    if (listItem) {
+      listItem.classList.add('table-of-content__list-item--active');
+    }
+  }
+}

src/frontend/styles/components/table-of-content.pcss

@@ -0,0 +1,60 @@
+.table-of-content {
+  position: sticky;
+  max-height: 100vh;
+  overflow-y: auto;
+
+  margin-top: 30px;
+  top: 30px;
+  width: 300px;
+  border-left: 1px solid #E8E8EB;
+  padding-left: 22px;
+
+  &__header {
+    font-size: 16px;
+    font-weight: 600;
+    line-height: 21px;
+    letter-spacing: -0.01em;
+
+    margin-bottom: 12px;
+    padding: 0 6px;
+  }
+
+  &__list {
+    margin: 0;
+
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+    padding: 0;
+
+    list-style: none;
+
+    gap: 6px;
+
+    &-item {
+      border-radius: 8px;
+
+      &:hover {
+        background-color: #F3F6F8;
+        cursor: pointer;
+      }
+
+      &--active {
+        background-color: #F3F6F8;
+      }
+
+      &--h3 { margin-left: 6px; }
+      &--h4 { margin-left: 12px; }
+      &--h5 { margin-left: 18px; }
+      &--h6 { margin-left: 24px; }
+
+      & > a {
+        margin: 4px 8px;
+        display: block;
+        font-size: 14px;
+        letter-spacing: -0.01em;
+        line-height: 150%;
+      }
+    }
+  }
+}

src/frontend/styles/layout.pcss

@@ -31,6 +31,16 @@
       max-width: var(--layout-width-main-col);
       margin: 0 auto;
     }
+
+    @media not (--mobile) {
+      margin-bottom: 80vh;
+    }
+  }
+
+  &__aside-right {
+    @media (--mobile) {
+      display: none;
+    }
   }
 
   &__aside,

src/frontend/styles/main.pcss

@@ -9,6 +9,7 @@
 @import './components/landing.pcss';
 @import './components/auth.pcss';
 @import './components/button.pcss';
+@import './components/table-of-content.pcss';
 
 body {
   font-family: system-ui, Helvetica, Arial, Verdana;