docs: add docs about lint html in js template literal (#245)

* docs: add docs about lint html in js template literal * Update .prettierignore
yeonjuan · Dec 5, 2024 · fc08374 · fc08374
1 parent 8a9492a
commit fc08374
Show file tree

Hide file tree

Showing 18 changed files with 464 additions and 391 deletions.
diff --git a/.prettierignore b/.prettierignore
@@ -2,9 +2,7 @@
 **/fixtures
 **/__snapshots__
 lerna.json
-packages/website/out
-packages/website/src/out
-packages/website/**/*.html
+packages/website/
 packages/web-linter/out
 .next
 dist

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -1,5 +1,15 @@
 # Getting Started
 
+## Contents
+
+- [Prerequisite](#prerequisite)
+- [Installation](#installation)
+- [Configuration](#configuration)
+  - [Flat config](#flat-config)
+  - [eslintrc config (.eslintrc.\*)](#eslintrc-config-eslintrc)
+- [Lint HTML in JavaScript Template Literal](#lint-html-in-javascript-template-literals)
+- [Editor Configuration](#editor-configuration)
+
 ## Prerequisite
 
 - Node.js: `^12.22.0 || ^14.17.0 || >=16.0.0`.
@@ -156,6 +166,57 @@ module.exports = {
 };
 ```
 
+## Lint HTML in JavaScript Template Literals
+
+This plugin provides the ability to lint not only HTML files, but also HTML written in [JavaScript Template Literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals).
+You can set the [@html-eslint rules](./rules.md) in your settings to lint JavaScript code without any additional configuration.
+
+```js,eslint.config.js
+import eslintHTML from "@html-eslint/eslint-plugin";
+export default [
+  // You can use the @html-eslint rules in your ESLint configuration for JS!
+  // This is used to lint HTML written inside Template Literal.
+  "plugins": {
+    "@html-eslint": eslintHTML
+  },
+  "rules": {
+    // Specifies the @html-eslint rules to apply to Template Literal.
+    "@html-eslint/no-inline-styles": 1,
+    "@html-eslint/indent": 1,
+  }
+];
+```
+
+Not all Template literals are recognized as HTML.
+There are two ways to get the plugin to recognize them as HTML.
+
+```js
+// 1. Tagged Templates with a function named `html`
+html` <div style="${style}"></div>`;
+
+// 2. Template Literal after a html comment (/* html */)
+const code = /* html */ `<div style="${style}"></div>`;
+```
+
+If you want to specify that linting should be done with keywords other than `html`, you can change the settings option.
+
+```js
+ {
+    "plugins": {
+      "@html-eslint": eslintHTML
+    },
+    settings: {
+        html: {
+          templateLiterals: {
+               // default options
+               tags: ["^html$"],
+               comments: ["^\\s*html\\s*$"],
+          }
+        }
+    },
+}
+```
+
 ## Editor Configuration
 
 ### VSCode

diff --git a/packages/website/.eslintrc.js b/packages/website/.eslintrc.js
@@ -2,6 +2,15 @@ module.exports = {
   root: true,
   plugins: ["@html-eslint"],
   parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+  rules: {
+    "@html-eslint/indent": ["error", 2],
+    "@html-eslint/element-newline": "error",
+    "@html-eslint/lowercase": "error",
+    "@html-eslint/no-extra-spacing-attrs": "error",
+    "@html-eslint/no-multiple-empty-lines": "error",
+    "@html-eslint/no-trailing-spaces": "error",
+    "@html-eslint/quotes": "error",
+  },
   overrides: [
     {
       files: ["**/*.html"],

diff --git a/packages/website/scripts/generates/renderer.js b/packages/website/scripts/generates/renderer.js
@@ -12,7 +12,10 @@ module.exports = {
     const id = text
       .toLowerCase()
       .replace(/^@/, "")
-      .replace(/[\s\/]/g, "-");
+      .replace(/[^a-zA-Z0-9]/g, "-")
+      .replace(/[\s\/]/g, "-")
+      .replace(/-+/g, "-")
+      .replace(/-$/, "");
     return `
     <h${level} id="${id}" class="group md-heading${level}">
       ${text}
@@ -56,10 +59,12 @@ module.exports = {
     `;
   },
   link(href, title, text) {
-    if (href.indexOf("http") === 0) {
-      text += `<img class="inline" src="~/src/assets/icon-external-link.svg" alt="" width="20" height="20">`;
+    const isExternal = href.indexOf("http") === 0;
+    if (isExternal) {
+      text += /* html */ `<img class="inline" src="~/src/assets/icon-external-link.svg" alt="" width="20" height="20">`;
     }
-    return `<a href="${href}" class="md-a" target="_blank" rel="noopener noreferrer">${text}</a>`;
+    href = href.replace(/\.md$/, "");
+    return /* html */ `<a href="${href}" target="${isExternal ? "blank" : ""}" class="md-a" rel="noopener noreferrer">${text}</a>`;
   },
   tablecell(content, flags) {
     if (flags.header) {

diff --git a/packages/website/src/common.css b/packages/website/src/common.css
@@ -79,7 +79,7 @@
     @apply list-disc body3 text-black-700 pl-[20px];
   }
   .md-listitem {
-    @apply my-[14px];
+    @apply my-[12px];
   }
   .md-p {
     @apply body3 text-black-700 py-[6px];
@@ -100,10 +100,10 @@
     @apply display1 text-black-900 my-[28px];
   }
   .md-heading2 {
-    @apply display3 text-black-900 my-[12px];
+    @apply display3 text-black-900 mb-3 mt-6;
   }
   .mad-heading3 {
-    @apply text-lg my-2 md:text-xl scroll-mt-[64px];
+    @apply text-lg mb-3 mt-5 md:text-xl scroll-mt-[64px];
   }
   .md-heading4 {
     @apply my-2 block scroll-mt-[64px];

diff --git a/packages/website/src/components/footer.html b/packages/website/src/components/footer.html
@@ -1,27 +1,27 @@
 
 <footer class="border-t h-[150px] shadow-[0_-1px_0_0_#E8EBEF] body5 {{class}}">
-    <section class="m-auto flex w-full md:max-w-[1200px] pt-[32px] pb-[54px] px-[24px]">
-        <div class="flex flex-col">
-            <ul>
-                <li>
-                    <a
-                        href="https://github.com/yeonjuan/html-eslint/issues"
-                        target="_blank noreferrer"
-                        class="text-slate-600"
-                    >Report issue</a>
-                </li>
-            </ul>
-            <span class="text-black-500">Copyright © 2023 html-eslint</span>
-        </div>
-        <div class="ml-auto">
-            <a href="https://github.com/yeonjuan/html-eslint">
-                <img
-                    src="~/src/assets/github.svg"
-                    alt="github"
-                    width="19px"
-                    height="19px"
-                >
-            </a>
-        </div>
-    </section>
+  <section class="m-auto flex w-full md:max-w-[1200px] pt-[32px] pb-[54px] px-[24px]">
+    <div class="flex flex-col">
+      <ul>
+        <li>
+          <a
+            href="https://github.com/yeonjuan/html-eslint/issues"
+            target="_blank noreferrer"
+            class="text-slate-600"
+          >Report issue</a>
+        </li>
+      </ul>
+      <span class="text-black-500">Copyright © 2023 html-eslint</span>
+    </div>
+    <div class="ml-auto">
+      <a href="https://github.com/yeonjuan/html-eslint">
+        <img
+          src="~/src/assets/github.svg"
+          alt="github"
+          width="19px"
+          height="19px"
+        >
+      </a>
+    </div>
+  </section>
 </footer>
diff --git a/packages/website/src/components/header/header.html b/packages/website/src/components/header/header.html
@@ -22,34 +22,34 @@
 }
 </style>
 <header class="flex fixed top-0 bg-white w-full z-50 flex-row items-center h-[66px] px-[20px] drop-shadow-[0_1px_#E8EBEF]">
-    <a class="flex flex-row items-center md:py-0 no-underline text-black text-base text-[20px] font-[800]" href="/">
-        <img
-            src="~/src/assets/logo.svg"
-            alt=""
-            class="inline w-[21px] mr-[11px]"
-            width="21"
-            height="24"
-        >
-        html-eslint
-    </a>
-    <span class="body8 inline-block bg-gray-200 text-black-500 rounded-[12px] px-[8px] py-[5px] mx-[8px]">
-        v{{ version }}
-    </span>
-    <input
-        id="menu"
-        type="checkbox"
-        class="menuInput peer sr-only hidden"
-        aria-hidden="true"
+  <a class="flex flex-row items-center md:py-0 no-underline text-black text-base text-[20px] font-[800]" href="/">
+    <img
+      src="~/src/assets/logo.svg"
+      alt=""
+      class="inline w-[21px] mr-[11px]"
+      width="21"
+      height="24"
     >
-    <label
-        for="menu"
-        aria-label="menu button"
-        class="burger flex flex-col justify-between ml-auto h-[21px] w-[21px] px-[1px] py-[3px] [&>div]:h-[2px] [&>div]:w-[18px] [&>div]:bg-black-900 md:hidden hover:cursor-pointer"
-    >
-        <div></div>
-        <div></div>
-        <div></div>
-    </label>
-    <module href="/components/header/nav.html"></module>
+    html-eslint
+  </a>
+  <span class="body8 inline-block bg-gray-200 text-black-500 rounded-[12px] px-[8px] py-[5px] mx-[8px]">
+    v{{ version }}
+  </span>
+  <input
+    id="menu"
+    type="checkbox"
+    class="menuInput peer sr-only hidden"
+    aria-hidden="true"
+  >
+  <label
+    for="menu"
+    aria-label="menu button"
+    class="burger flex flex-col justify-between ml-auto h-[21px] w-[21px] px-[1px] py-[3px] [&>div]:h-[2px] [&>div]:w-[18px] [&>div]:bg-black-900 md:hidden hover:cursor-pointer"
+  >
+    <div></div>
+    <div></div>
+    <div></div>
+  </label>
+  <module href="/components/header/nav.html"></module>
 </header>
 
diff --git a/packages/website/src/components/header/nav.html b/packages/website/src/components/header/nav.html
@@ -1,32 +1,32 @@
 <nav class="fixed transition-[max-height] duration-200 overflow-hidden max-h-0 top-[67px] left-[0px] peer-checked:max-h-[200px] bg-white w-full md:ml-auto md:flex md:top-auto md:max-h-max md:relative md:w-auto md:peer-checked:translate-y-0">
-    <ul class="body2 flex flex-col text-black-500 p-[12px] [&>li>a]:px-[16px] [&>li>a]:py-[12px] [&>li]:rounded-[10px] md:[&>li>a]:px-0 md:[&>li>a]:py-0  md:title5 md:gap-[24px] md:flex-row md:p-0">
-        <li
-            class="hover:text-black-900 hover:bg-gray-200 md:hover:bg-white"
-            data-nav="/docs"
-            data-nav-active="text-black-900"
+  <ul class="body2 flex flex-col text-black-500 p-[12px] [&>li>a]:px-[16px] [&>li>a]:py-[12px] [&>li]:rounded-[10px] md:[&>li>a]:px-0 md:[&>li>a]:py-0  md:title5 md:gap-[24px] md:flex-row md:p-0">
+    <li
+      class="hover:text-black-900 hover:bg-gray-200 md:hover:bg-white"
+      data-nav="/docs"
+      data-nav-active="text-black-900"
+    >
+      <a href="~/src/docs/getting-started.html" class="w-full h-full flex justify-center flex-col">
+        <span>Docs</span>
+      </a>
+    </li>
+    <li
+      class="hover:text-black-900 hover:bg-gray-200 md:hover:bg-white"
+      data-nav="/playground"
+      data-nav-active="text-black-900"
+    >
+      <a href="~/src/playground.html" class="w-full h-full flex justify-center flex-col">Playground</a>
+    </li>
+    <li class="hover:text-black-900 hover:bg-gray-200 md:hover:bg-white">
+      <a href="https://github.com/yeonjuan/html-eslint" class="w-full h-full flex justify-center flex-col">
+        <img
+          src="~/src/assets/github.svg"
+          width="26"
+          height="26"
+          alt="github"
+          class="hidden md:block"
         >
-            <a href="~/src/docs/getting-started.html" class="w-full h-full flex justify-center flex-col">
-                <span>Docs</span>
-            </a>
-        </li>
-        <li
-            class="hover:text-black-900 hover:bg-gray-200 md:hover:bg-white"
-            data-nav="/playground"
-            data-nav-active="text-black-900"
-        >
-            <a href="~/src/playground.html" class="w-full h-full flex justify-center flex-col">Playground</a>
-        </li>
-        <li class="hover:text-black-900 hover:bg-gray-200 md:hover:bg-white">
-            <a href="https://github.com/yeonjuan/html-eslint" class="w-full h-full flex justify-center flex-col">
-                <img
-                    src="~/src/assets/github.svg"
-                    width="26"
-                    height="26"
-                    alt="github"
-                    class="hidden md:block"
-                >
-                <span class="md:hidden">Github</span>
-            </a>
-        </li>
-    </ul>
+        <span class="md:hidden">Github</span>
+      </a>
+    </li>
+  </ul>
 </nav>