Add section comments and format HTML for improved readability (#2158)

.changeset/unlucky-sloths-tie.md

@@ -0,0 +1,4 @@
+---
+---
+
+Add section comments and format HTML for improved readability

package.json

@@ -25,6 +25,7 @@
     "concurrently": "^9.1.2",
     "cross-env": "^7.0.3",
     "glob": "^11.0.1",
+    "htmlfy": "^0.6.0",
     "js-beautify": "^1.15.1",
     "nodemon": "^3.1.9",
     "pnpm": "9.15.4",
@@ -34,8 +35,8 @@
     "rollup": "4.34.4",
     "rtlcss": "^4.3.0",
     "sass": "1.71.0",
+    "shx": "^0.3.4",
     "terser": "^5.38.1",
-    "turbo": "^2.4.0",
-    "shx": "^0.3.4"
+    "turbo": "^2.4.0"
   }
 }

pnpm-lock.yaml

@@ -44,6 +44,9 @@ importers:
       glob:
         specifier: ^11.0.1
         version: 11.0.1
+      htmlfy:
+        specifier: ^0.6.0
+        version: 0.6.0
       js-beautify:
         specifier: ^1.15.1
         version: 1.15.1
@@ -2211,6 +2214,10 @@ packages:
     resolution: {integrity: sha512-mxIDAb9Lsm6DoOJ7xH+5+X4y1LU/4Hi50L9C5sIswK3JzULS4bwk1FvjdBgvYR4bzT4tuUQiC15FE2f5HbLvYw==}
     dev: true
 
+  /[email protected]:
+    resolution: {integrity: sha512-EV1RNjYuG6xIxwA8zDjAUQVeS/SsPE0nhFsdjM8ALopS22ZRAcePocdrhKaaV26PYiTkUrKplJuSZkGRN6Y0Rg==}
+    dev: true
+
   /[email protected]:
     resolution: {integrity: sha512-H7MImA4MS6cw7nbyURtLPO1Tms7C5H602LRETv95z1MxO/7CP7rDVROehUYeYBUYEON94NXXDEPmZuq+hX4sog==}
     dependencies:

preview/eleventy.config.mjs

@@ -590,14 +590,16 @@ export default function (eleventyConfig) {
 	/**
 	 * Transforms
 	 */
-	function prettifyHTML(content, outputPath) {
-		return outputPath.endsWith('.html')
-			? content
-				.replace(/\/\/ @formatter:(on|off)\n+/gm, '')
-				// remove empty lines
-				.replace(/^\s*[\r\n]/gm, '')
-			: content
-	}
+	if (environment !== "development") {
+		function prettifyHTML(content, outputPath) {
+			return outputPath.endsWith('.html')
+				? content
+					.replace(/\/\/ @formatter:(on|off)\n+/gm, '')
+					// remove empty lines
+					.replace(/^\s*[\r\n]/gm, '')
+				: content
+		}
 
-	eleventyConfig.addTransform('htmlformat', prettifyHTML)
+		eleventyConfig.addTransform('htmlformat', prettifyHTML)
+	}
 };

preview/package.json

@@ -18,7 +18,9 @@
     "js-minify-demo": "terser --compress passes=2 --mangle --comments \"/^!/\" --source-map \"content=dist/preview/js/demo.js.map,includeSources,url=demo.min.js.map\" --output dist/preview/js/demo.min.js dist/preview/js/demo.js",
     "js-minify-theme": "terser --compress passes=2 --mangle --comments \"/^!/\" --source-map \"content=dist/preview/js/demo-theme.js.map,includeSources,url=demo-theme.min.js.map\" --output dist/preview/js/demo-theme.min.js dist/preview/js/demo-theme.js", 
     "clean": "shx rm -rf dist demo",
-    "html": "eleventy",
+    "html": "pnpm run html-build && pnpm run html-prettify",
+    "html-build": "eleventy",
+    "html-prettify": "prettier --write \"dist/**/*.html\"",
     "svg-optimize": "svgo -f svg/brand --pretty",
     "unused-files": "node build/unused-files.mjs",
     "download-images": "node build/download-images.mjs",
@@ -55,5 +57,10 @@
     "imageoptim-cli": "^3.1.9",
     "@11ty/eleventy": "^3.0.0",
     "@repo/banner": "workspace:*"
+  },
+  "prettier": {
+    "tabWidth": 2,
+    "useTabs": false,
+    "printWidth": 160
   }
 }

preview/pages/_includes/cards/user-card-bg.html

@@ -1,7 +1,7 @@
 {% assign person-id = include.person-id | default: 0 %}
 {% assign person = people[person-id] %}
 <a class="card card-link" href="#">
-	<div class="card-cover card-cover-blurred text-center{% if include.blurred %} card-cover-blurred{% endif %}" style="background-image: url({% include "ui/photo.html" id=person-id %})">
+	<div class="card-cover card-cover-blurred text-center{% if include.blurred %} card-cover-blurred{% endif %}" style="background-image: url({{ page | relative }}/static/photos/{{ photos[person-id].file }})">
 		{% include "ui/avatar.html" size="xl" person=person thumb=true rounded=true %}
 	</div>
 	<div class="card-body text-center">

preview/pages/_includes/layout/css.html

@@ -1,10 +1,12 @@
-<!-- CSS files -->
 {% if site.useIconfont %}
+<!-- BEGIN ICONFONT STYLES -->
 <link href="https://www.unpkg.com/@tabler/icons-webfont@latest/dist/tabler-icons.min.css" rel="stylesheet" />
+<!-- END ICON FONT STYLES -->
 {% endif %}
 
 
 {% if page-libs %}
+<!-- BEGIN PAGE LEVEL STYLES -->
 	{% for lib in libs.css %}
 		{% if page-libs contains lib[0] %}
 			{% for file in lib[1] %}
@@ -12,12 +14,19 @@
 			{% endfor %}
 		{% endif %}
 	{% endfor %}
+<!-- END PAGE LEVEL STYLES -->
 {% endif %}
 
+<!-- BEGIN GLOBAL MANDATORY STYLES -->
 <link href="{{ page | relative }}/dist/css/tabler{% if layout-rtl %}.rtl{% endif %}{% if environment != 'development' %}.min{% endif %}.css{% if environment != 'development' %}?{{ 'now' | date: '%s' }}{% endif %}" rel="stylesheet"/>
+<!-- END GLOBAL MANDATORY STYLES -->
 
+<!-- BEGIN PLUGINS STYLES -->
 {% for plugin in site.tablerCssPlugins %}
 	<link href="{{ page | relative }}/dist/css/{{ plugin }}{% if layout-rtl %}.rtl{% endif %}{% if environment != 'development' %}.min{% endif %}.css{% if environment != 'development' %}?{{ 'now' | date: '%s' }}{% endif %}" rel="stylesheet"/>
 {% endfor %}
+<!-- END PLUGINS STYLES -->
 
-<link href="{{ page | relative }}/preview/css/demo{% if layout-rtl %}.rtl{% endif %}{% if environment != 'development' %}.min{% endif %}.css{% if environment != 'development' %}?{{ 'now' | date: '%s' }}{% endif %}" rel="stylesheet"/>
+<!-- BEGIN DEMO STYLES -->
+<link href="{{ page | relative }}/preview/css/demo{% if layout-rtl %}.rtl{% endif %}{% if environment != 'development' %}.min{% endif %}.css{% if environment != 'development' %}?{{ 'now' | date: '%s' }}{% endif %}" rel="stylesheet"/>
+<!-- END DEMO STYLES -->

preview/pages/_includes/layout/debug.html

@@ -1,81 +0,0 @@
-<div class="debug">
-	<a href="#" data-debug="dark">Dark mode</a>
-	<a href="#" data-debug="rtl">RTL mode</a>
-	<a href="#" data-debug="code">Show cards code</a>
-	<a href="#" data-debug="folded">Folded sidebar</a>
-	<a href="#" data-debug="fullscreen">Fullscreen</a>
-	<a href="#" data-debug="header-sticky">Sticky header</a>
-	<a href="{{ page | relative }}/pages.html">All pages</a>
-</div>
-<style>
-	.card-debug {
-		position: absolute;
-		right: 0;
-		top: 0;
-		line-height: 1;
-		font-size: 11px;
-		display: none;
-	}
-
-	.debug-info {
-		margin-left: auto;
-	}
-
-	.card-debug a {
-		display: inline-block;
-		padding: 2px;
-	}
-
-	.card-debug a:hover {
-		text-decoration: underline;
-	}
-
-	.debug {
-		position: fixed;
-		bottom: 0;
-		left: 0;
-		right: 0;
-		background: #222;
-		color: #fff;
-		padding: .5rem .75rem;
-		font-size: 12px;
-		direction: ltr;
-		text-align: left;
-		z-index: 3000;
-		display: flex;
-	}
-
-	.debug a {
-		color: inherit;
-		margin-right: 1rem;
-	}
-
-	.debug a[data-debug]:after {
-		content: "";
-		margin: 0 0 1px .25rem;
-		width: 6px;
-		height: 6px;
-		display: inline-block;
-		background: rgba(255, 255, 255, .3);
-		border-radius: $border-radius-pill;
-	}
-
-	body.show-debug-code .card-debug {
-		display: block;
-	}
-
-	@media (max-width: 991.98px) {
-		.debug {
-			display: none;
-		}
-	}
-
-	body.show-debug-code a[data-debug="code"]:after,
-	html[dir="rtl"] a[data-debug="rtl"]:after,
-	body.theme-dark a[data-debug="dark"]:after,
-	:fullscreen a[data-debug="fullscreen"]:after,
-	body.header-sticky a[data-debug="header-sticky"]:after,
-	body.sidebar-folded a[data-debug="folded"]:after {
-		background: #5eba00;
-	}
-</style>

preview/pages/_includes/layout/footer.html

@@ -1,3 +1,4 @@
+<!--  BEGIN FOOTER  -->
 <footer class="footer footer-transparent d-print-none">
 	<div class="container-xl">
 		<div class="row text-center align-items-center flex-row-reverse">
@@ -34,4 +35,6 @@
 			</div>
 		</div>
 	</div>
-</footer>
+</footer>
+<!--  END FOOTER  -->
+  

preview/pages/_includes/layout/js.html

@@ -1,4 +1,4 @@
-<!-- Libs JS -->
+<!-- BEGIN PAGE LEVEL SCRIPTS -->
 {% assign google-maps-key = site.googleMapsDevKey -%}
 {% if environment != 'development' -%}
 	{% assign google-maps-key = site.googleMapsKey -%}
@@ -13,12 +13,15 @@
 		{% endif -%}
 	{% endfor -%}
 {% endif -%}
+<!-- END PAGE LEVEL SCRIPTS -->
 
-<!-- Tabler Core -->
-
+<!-- BEGIN GLOBAL MANDATORY SCRIPTS -->
 <script src="{{ page | relative }}/dist/js/tabler{% if environment != 'development' %}.min{% endif %}.js{% if environment != 'development' %}?{{ 'now' | date: '%s' }}{% endif %}" defer></script>
-<script src="{{ page | relative }}/preview/js/demo{% if environment != 'development' %}.min{% endif %}.js{% if environment != 'development' %}?{{ 'now' | date: '%s' }}{% endif %}" defer></script>
+<!-- END GLOBAL MANDATORY SCRIPTS -->
 
+<!-- BEGIN DEMO SCRIPTS -->
+<script src="{{ page | relative }}/preview/js/demo{% if environment != 'development' %}.min{% endif %}.js{% if environment != 'development' %}?{{ 'now' | date: '%s' }}{% endif %}" defer></script>
+<!-- END DEMO SCRIPTS -->
 
 {% for script in site.captured_global.scripts %}
 {{ script }}

preview/pages/_includes/layout/navbar-logo.html

@@ -1,3 +1,4 @@
+<!-- BEGIN NAVBAR LOGO -->
 {% assign prefix = include.prefix | default: 'navbar' %}
 {% assign breakpoint = include.breakpoint | default: 'lg' %}
 
@@ -32,4 +33,5 @@
 </div>
 {% else %}
 </a>
-{% endif %}
+{% endif %}
+<!-- END NAVBAR LOGO -->

preview/pages/_includes/layout/navbar-menu.html

@@ -1,3 +1,4 @@
+<!-- BEGIN NAVBAR MENU -->
 {% assign current-page = page-menu | default: layout.menu | split: '.' %}
 {% assign hide-icons = include.hide-icons %}
 {% assign icons-count = icons-info.count %}
@@ -90,4 +91,5 @@
 		</a>
 	</li>
 	{% endcomment %}
-</ul>
+</ul>
+<!-- END NAVBAR MENU -->

preview/pages/_includes/layout/navbar-toggler.html

@@ -1,3 +1,5 @@
+<!-- BEGIN NAVBAR TOGGLER -->
 <button class="navbar-toggler" type="button" data-bs-toggle="collapse"{% if include.target %} data-bs-target="#{{ include.target }}" aria-controls="{{ include.target }}"{% endif %} aria-expanded="false" aria-label="Toggle navigation">
 	<span class="navbar-toggler-icon"></span>
-</button>
+</button>
+<!-- END NAVBAR TOGGLER -->

preview/pages/_includes/layout/page-header.html

@@ -1,3 +1,4 @@
+<!-- BEGIN PAGE HEADER -->
 {% assign page-header = page-header | default: layout.page-header %}
 {% assign description = page-header-description | default: layout.page-header-description %}
 {% assign actions = page-header-actions | default: layout.page-header-actions %}
@@ -8,7 +9,6 @@
 {% if page-header-file %}
 	{% include "layout/headers/{{ page-header-file }}.html" %}
 {% elsif page-header %}
-<!-- Page header -->
 <div class="page-header{% if class %} {{ class }}{% endif %} d-print-none{% if layout-navbar-overlap and layout-navbar-dark %} text-white{% endif %}">
 	<div class="container-xl">
 		<div class="row g-2 align-items-center">
@@ -40,4 +40,5 @@
 		</div>
 	</div>
 </div>
-{% endif %}
+{% endif %}
+<!-- END PAGE HEADER -->

preview/pages/_includes/ui/modal.html

@@ -1,3 +1,4 @@
+<!-- BEGIN MODAL -->
 {% assign modal-id = include.modal-id | default: 'simple' %}
 {% assign size = include['size'] %}
 
@@ -9,4 +10,5 @@
 		</div>
 	</div>
 </div>
-{% endcapture_global %}
+{% endcapture_global %}
+<!-- END MODAL -->

preview/pages/_layouts/base.html

@@ -31,23 +31,23 @@
 
 	{% include "layout/css.html" %}
 
+	<!-- BEGIN CUSTOM FONT -->
 	<style>
 		@import url('https://rsms.me/inter/inter.css');
 	</style>
+	<!-- END CUSTOM FONT -->
 </head>
 
 {% assign layout-dark = layout-dark | default: site.layoutDark %}
 <body{% if layout.body-class or body-class %} class="{% if layout.body-class %} {{ layout.body-class }}{% endif %}{% if body-class %} {{ body-class }}{% endif %}"{% endif %}>
-<script src="{{ page | relative }}/preview/js/demo-theme{% if environment != 'development' %}.min{% endif %}.js{% if environment != 'development' %}?{{ 'now' | date: '%s' }}{% endif %}"></script>
+	<!-- BEGIN DEMO THEME SCRIPT -->
+	<script src="{{ page | relative }}/preview/js/demo-theme{% if environment != 'development' %}.min{% endif %}.js{% if environment != 'development' %}?{{ 'now' | date: '%s' }}{% endif %}"></script>
+	<!-- END DEMO THEME SCRIPT -->
 
 	{{ content }}
 
 	{% include "layout/modals-capture.html" %}
 
 	{% include "layout/js.html" %}
-
-	{% if site.debug and environment == 'development' %}
-		{% include "layout/debug.html" %}
-	{% endif %}
 </body>
 </html>

preview/pages/_layouts/default.html

@@ -6,19 +6,21 @@ layout: base
 
 <div class="page">
 	{% if layout-sidebar %}
-		<!-- Sidebar -->
+		<!--  BEGIN SIDEBAR  -->
 		{% include "layout/sidebar.html" dark=layout-sidebar-dark right=layout-sidebar-right transparent=layout-navbar-transparent breakpoint="lg" %}
+		<!--  END SIDEBAR  -->
 	{% endif %}
 
 	{% unless layout-hide-topbar %}
-		<!-- Navbar -->
+		<!-- BEGIN NAVBAR  -->
 		{% include "layout/navbar.html" condensed=layout-navbar-condensed overlap=layout-navbar-overlap dark=layout-navbar-dark hide-brand=layout-navbar-hide-brand hide-menu=layout-navbar-hide-menu sticky=layout-navbar-sticky transparent=layout-topbar-transparent class=layout-navbar-class %}
+		<!-- END NAVBAR  -->
 	{% endunless %}
 
 	<div class="page-wrapper{% if layout-wrapper-full %} page-wrapper-full{% endif %}">
 		{% include "layout/page-header.html" %}
 
-		<!-- Page body -->
+		<!-- BEGIN PAGE BODY -->
 		<div class="page-body">
 			{% if layout-wrapper-full %}
 			{{ content }}
@@ -33,6 +35,7 @@ layout: base
 
 			{% endif %}
 		</div>
+		<!-- END PAGE BODY -->
 
 		{% include "layout/footer.html" %}
 	</div>

turbo.json

@@ -1,5 +1,8 @@
 {
   "$schema": "https://turbo.build/schema.json",
+  "globalEnv": [
+    "NODE_ENV"
+  ],
   "tasks": {
     "build": {
       "dependsOn": [