Add Introduction Article (#94)

* refactor: external links

* limit article max-width to improve readability

* refactor: article headings

* shrink text on smaller screens

* fix: accordions and improve space usage

* doc: clarify runtime.special a bit

* determine remark display mode automatically to save space

* revert: accordion JS

* doc: improve clarity and example for definition files

* doc: improve description for export-docs

* fix: decrease min width for 3 column article mode

* fix: external link colouring

* fix: external link wrapping

* fix: remark icon colouring

* doc: make remark block

* add: background to focus outline

* add: levels of bolding to headings

* refactor: wiki article heading spacing

* add: aria labels to article action buttons

* fix: increase heading target highlight size

* add: more spacing for external link icon

* doc: add introduction article

Author: carsakiller

src/components/common/Accordion.astro

@@ -41,7 +41,7 @@ const open = Astro.props.open ?? false;
 </script>
 
 <style lang="scss">
-  details {
+  details.accordion {
     position: relative;
     background-color: #1b1e1f;
     border-radius: 0.5em;
@@ -52,7 +52,6 @@ const open = Astro.props.open ?? false;
       align-items: center;
       list-style: none;
       padding: 0.25em;
-      user-select: none;
 
       :global(i.fa-chevron-right) {
         margin: 0px 1em 0px 0.5em;
@@ -77,6 +76,10 @@ const open = Astro.props.open ?? false;
     & > div.content {
       background-color: #131516;
       padding: 1em;
+
+      & > :global(:nth-child(1)) {
+        margin-top: 0px;
+      }
     }
 
     &[open] {

src/components/common/ExternalLink.astro

@@ -1,4 +1,5 @@
 ---
+import Icon from "./Icon.astro";
 import Tooltip from "./Tooltip.astro";
 
 const {
@@ -27,7 +28,10 @@ export interface Props {
   class?: string;
 }
 
-const classes = [className, "external"];
+const classes = ["external"];
+if (className) {
+  classes.push(className);
+}
 if (icon === false) {
   classes.push("no-icon");
 }
@@ -38,28 +42,43 @@ if (!refer) {
 }
 ---
 
-<Tooltip content={hostname}>
-  <a
-    href={url}
-    target={newTab ? "_blank" : null}
-    rel={relationships.join(" ")}
-    class={classes.join(" ")}
-    set:html={child}
-  />
-</Tooltip>
+<span class="external-link">
+  <Tooltip content={hostname}>
+    <a
+      href={url}
+      target={newTab ? "_blank" : null}
+      rel={relationships.join(" ")}
+      class={classes.join(" ")}
+      set:html={child}
+    />{
+      icon !== false && (
+        <Icon
+          group="solid"
+          name="up-right-from-square"
+          class="external-indicator"
+        />
+      )
+    }
+  </Tooltip>
+</span>
 
 <style lang="scss">
-  a.external {
+  .external-link {
     color: var(--link-color);
-    font-weight: 500;
-    white-space: normal;
-  }
-  a.external:not(.no-icon)::after {
-    content: "\f08e";
-    vertical-align: text-top;
-    font-family: "Font Awesome 7 Free";
-    font-size: 0.5em;
-    display: inline-block;
-    padding-left: 0.2em;
+
+    &:not(.no-icon) {
+      margin-right: -0.2em;
+    }
+
+    a {
+      font-weight: 500;
+    }
+
+    & > :global(.tooltip > .icon.external-indicator) {
+      display: inline;
+      margin-left: -0.3em;
+      vertical-align: text-top;
+      font-size: 0.4em;
+    }
   }
 </style>

src/components/common/Icon.astro

@@ -19,7 +19,7 @@ export interface Props {
 ---
 
 <i
-  class:list={[`fa-${group}`, `fa-${name}`, className]}
+  class:list={[`fa-${group}`, `fa-${name}`, "icon", className]}
   aria-label={ariaLabel}
   style={styles}
 >

src/components/common/Remark.astro

@@ -8,6 +8,7 @@ const TYPES = {
   WIP: { displayName: "WIP", icon: "pen-ruler" },
   deprecated: { displayName: "Deprecated", icon: "trash-can" },
   issue: { displayName: "Issue", icon: "circle-dot" },
+  recommendation: {displayName: "Recommendation", icon: "asterisk"}
 };
 
 type RemarkType =
@@ -16,7 +17,8 @@ type RemarkType =
   | "important"
   | "WIP"
   | "deprecated"
-  | "issue";
+  | "issue"
+  | "recommendation"
 
 export interface Props {
   type: RemarkType;
@@ -31,15 +33,31 @@ if (!remark) {
   throw new Error("Invalid remark type: " + type);
 }
 
-const classList = [type, "remark", display ?? "block"];
+const classList = [type, "remark"];
+
+if (display) {
+  classList.push(display);
+} else {
+  // If display mode is not specified, fetch the slot text content length and determine best mode.
+  const content = await Astro.slots.render("default");
+  const text = content.replace(/<[^>]*>/g, "").replace(/\s+/g, ' ').trim();
+
+  if (text.length < 115) {
+    classList.push("compact");
+  } else {
+    classList.push("block");
+  }
+}
 ---
 
 <div class:list={classList}>
   <div>
     <Icon name={remark.icon} group="solid" />
     {remark.displayName}
   </div>
-  <slot />
+  <div class="content">
+    <slot />
+  </div>
 </div>
 
 <style lang="scss">
@@ -55,17 +73,13 @@ const classList = [type, "remark", display ?? "block"];
     background-color: color-mix(in srgb, var(--remark-color), #071521 80%);
 
     &.block {
-      width: 90%;
+      width: 95%;
     }
 
     &.compact {
       display: flex;
       align-items: center;
       gap: 0.5em;
-
-      & > :global(*) {
-        margin: 0px;
-      }
     }
 
     &.note {
@@ -92,21 +106,28 @@ const classList = [type, "remark", display ?? "block"];
       --remark-color: #2ea043;
     }
 
-    & > div {
+    &.recommendation {
+      --remark-color: #1aecbe;
+    }
+
+    & > div:first-of-type {
       font-size: 1.1em;
       display: flex;
-      gap: 0.5em;
+      gap: 0.2em;
       align-items: center;
       font-weight: bold;
-    }
 
-    :global(i.fa-solid) {
-      font-size: 1.3em;
-      color: color-mix(in srgb, var(--remark-color), white 60%);
+      :global(i.fa-solid) {
+        margin-left: -0.3em;
+        font-size: 1.3em;
+        color: color-mix(in srgb, var(--remark-color), white 60%);
+      }
     }
 
-    & > :global(p) {
-      margin: 0.5em auto 0.2em auto;
+    & > .content {
+      :global(p) {
+        margin: 0.1em auto;
+      }
     }
   }
 </style>

src/components/layout/Footer.astro

@@ -81,7 +81,7 @@ const { class: className } = Astro.props;
     }
 
     :global(a),
-    :global(a.external) {
+    :global(.external-link) {
       color: inherit;
       font-weight: normal;
     }

src/components/layout/Header.astro

@@ -1,5 +1,4 @@
 ---
-import ExternalLink from "../common/ExternalLink.astro";
 import Icon from "../common/Icon.astro";
 import Tooltip from "../common/Tooltip.astro";
 
@@ -25,20 +24,19 @@ const { class: className } = Astro.props;
       </a>
     </div>
     <Tooltip
-      content="<div align='center'>Search <br/><kbd>/</kbd></div>"
+      content="<div align='center'>Search<br/><kbd>/</kbd></div>"
       allowHTML
     >
       <button class="site-search-icon" aria-keyshortcuts="/">
         <Icon name="search" group="solid" ariaLabel="Search" />
       </button>
     </Tooltip>
     <span class="github">
-      <ExternalLink
-        url="https://github.com/luals/lua-language-server"
-        icon={false}
-      >
-        <Icon name="github" group="brands" />
-      </ExternalLink>
+      <a href="https://github.com/luals/lua-language-server">
+        <Tooltip content="View Project on GitHub">
+          <Icon name="github" group="brands" ariaLabel="View Project on GitHub"/>
+        </Tooltip>
+      </a>
     </span>
   </nav>
 </header>
@@ -78,8 +76,7 @@ const { class: className } = Astro.props;
         margin: auto;
       }
 
-      a,
-      :global(a.external) {
+      a{
         color: white;
       }
 

src/components/wiki/Heading.astro

@@ -12,27 +12,39 @@ import Icon from "../common/Icon.astro";
 ---
 
 <div class="heading" id={id}>
-  <a href={`#${id}`}><Icon name="link" group="solid" /></a>
-  <Element><slot /></Element>
+  <a href={`#${id}`}
+    ><Icon name="link" group="solid" class="icon" /><Element><slot /></Element
+    ></a
+  >
 </div>
 
 <style lang="scss">
   :global(details.accordion > summary div.heading) {
     margin: 0px;
+
+    & > a > :global(i.icon) {
+      display: none;
+    }
   }
 
   div.heading {
-    width: calc(100% + 3em);
-    margin: 2em 0px 0px -3em;
-    display: flex;
-    align-items: center;
+    width: calc(100%);
+    margin: 1em 0px 0.5em 0em;
+    line-height: 3ch;
 
     & > a {
       color: white;
-      opacity: 0;
-      font-size: 1.25em;
-      padding: 0.25em 0.5em;
-      transition: opacity 0.3s ease-in-out;
+      display: flex;
+      align-items: center;
+      position: relative;
+
+      & > :global(i.icon) {
+        position: absolute;
+        left: -1.75em;
+        font-size: 1.25em;
+        opacity: 0;
+        transition: opacity 0.3s ease-in-out;
+      }
     }
 
     :global(h1),
@@ -50,23 +62,18 @@ import Icon from "../common/Icon.astro";
       &::after {
         content: "";
         display: block;
-        width: 0.1em;
-        height: 100%;
-        background-color: var(--link-color);
+        width: calc(100% + 0.2em);
+        height: 140%;
+        background-color: #ff9500;
+        opacity: 0.2;
         position: absolute;
-        bottom: 0px;
-        border-radius: 99em;
-        left: -0.15em;
+        bottom: -24%;
+        border-radius: 0.1em;
+        left: -0.1em;
         z-index: -1;
         padding: 0px;
         clip-path: polygon(0 0, 0 0, 0 100%, 0% 100%);
-        transition: clip-path cubic-bezier(0.65, 0.05, 0.36, 1) 0.75s;
-      }
-    }
-
-    &:hover {
-      a {
-        opacity: 1;
+        transition: clip-path cubic-bezier(0.65, 0.05, 0.36, 1) 1s;
       }
     }
 
@@ -81,7 +88,7 @@ import Icon from "../common/Icon.astro";
           clip-path: polygon(0 0, 100% 0%, 100% 100%, 0% 100%);
         }
       }
-      a {
+      a > :global(i.icon) {
         opacity: 1;
       }
     }
@@ -94,10 +101,11 @@ import Icon from "../common/Icon.astro";
   @media screen and (max-width: 800px) {
     div.heading {
       width: 100%;
-      margin: 2em auto 0px -1.5em;
+      font-size: 0.8em;
+      margin: 2em 0px 0px 0px;
 
-      & > a {
-        font-size: 0.9em;
+      & > a > :global(i.icon) {
+        display: none;
       }
     }
   }

src/content/wiki/annotations.mdx

@@ -13,7 +13,7 @@ The language server does its best to infer types through contextual analysis, ho
 
 Annotations are prefixed with `---`, like a Lua comment with one extra dash.
 
-<Remark type="warning" display="compact">
+<Remark type="warning" display="block">
   LuaCATS annotations are [no longer
   cross-compatible](https://github.com/LuaLS/lua-language-server/issues/980)
   with [EmmyLua annotations](https://emmylua.github.io/annotation.html) as of