docs: add Get started: Developers (#1439)

* feat: add content and update template

* feat: add script tags to some code blocks

* feat: fix page order and headings

* fix: add script tags

* feat: updated installation content and code on Tokens subpage

* feat: change layout-with-subnav template and frontmatter

* fix: Change the link in the side nav from "Overview" to "Developers"

* feat: link to Developers page from Get Started: Overview

* feat: add usage content and update installation info

* fix: add script tags to code blocks

* docs: update docs/get-started/developers/tokens.md

* docs: update docs/get-started/developers/usage.md

* docs: react usage

---------

Co-authored-by: Benny Powers - עם ישראל חי! <[email protected]>
Co-authored-by: Benny Powers <[email protected]>

docs/_includes/component/header.njk

@@ -48,7 +48,7 @@
           </details>
         </li>
 
-        <!-- Get started -->
+        <!-- Get started (Subitems here use the heading in the frontmatter for the link text.) -->
 
         <li class="item">
           <details {{ 'open' if 'get-started/' in page.url }}>
@@ -61,7 +61,7 @@
               {%- for link in collections.getstarted -%}
               <li class="item">
                 <a class="link {{ 'active' if page.url === link.url }}"
-                   href="{{ link.url | url }}">{{ link.data.title }}</a>
+                   href="{{ link.url | url }}">{{ link.data.heading }}</a>
               </li>
               {%- endfor -%}
             </ul>

docs/_includes/layout-foundations.njk → docs/_includes/layout-with-subnav.njk

@@ -7,20 +7,24 @@ importElements:
   - rh-subnav
   - rh-tag
   - rh-badge
+  - rh-code-block
 ---
 
 {% include 'component/header.njk' %}
 
 <main class="l-main">
   <article class="l-main__inner">
     <header class="l-main__header l-main__header--palette-lighter">
-      <div class="container header has-subnav">
+      <div class="container header {% if subNavCollection %}has-subnav{% endif %}">
         <h1 id="{{ heading or title }}" class="page-title">{{ heading or title }}</h1>
-        <rh-subnav>{% for tab in collections.sortedColor %}
-          <a {{ 'active' if tab.url == page.url }} href="{{ tab.url }}">
-            {{ tab.data.title }}
-          </a>{% endfor %}
+        {% if subNavCollection %}
+        <rh-subnav>
+          {% for tab in collections[subNavCollection] %}
+            <a {{ 'active' if tab.url == page.url }} href="{{ tab.url }}">
+            {{ tab.data.title }}</a>
+          {% endfor %}
         </rh-subnav>
+        {% endif %}
       </div>
     </header>
     <div class="l-main__content">

docs/_plugins/rhds.cjs

@@ -230,6 +230,13 @@ module.exports = function(eleventyConfig, { tagsToAlphabetize }) {
     });
   });
 
+  eleventyConfig.addCollection('sortedDevelopers', async function(collectionApi) {
+    const developersCollection = collectionApi.getFilteredByTags('developers');
+    return developersCollection.sort((a, b) => {
+      if (a.data.order > b.data.order) { return 1; } else if (a.data.order < b.data.order) { return -1; } else { return 0; }
+    });
+  });
+
   eleventyConfig.addCollection('elementDocs', async function(collectionApi) {
     const { pfeconfig } = eleventyConfig?.globalData ?? {};
     /**

docs/foundations/color/accessibility.md

@@ -1,10 +1,11 @@
 ---
-layout: layout-foundations.njk
+layout: layout-with-subnav.njk
 title: Accessibility
 heading: Color
 tags:
   - color
 permalink: /foundations/color/accessibility/index.html
+subNavCollection: sortedColor
 order: 20
 bodyClasses: element-docs
 ---

docs/foundations/color/index.md

@@ -1,11 +1,12 @@
 ---
-layout: layout-foundations.njk
+layout: layout-with-subnav.njk
 title: Overview
 heading: Color
 tags:
   - foundations
   - color
 permalink: /foundations/color/index.html
+subNavCollection: sortedColor
 order: 00
 bodyClasses: element-docs
 ---

docs/foundations/color/usage.md

@@ -1,10 +1,11 @@
 ---
-layout: layout-foundations.njk
+layout: layout-with-subnav.njk
 title: Usage
 heading: Color
 tags:
   - color
 permalink: /foundations/color/usage/index.html
+subNavCollection: sortedColor
 order: 10
 bodyClasses: element-docs
 ---

docs/get-started.md

@@ -37,13 +37,15 @@ The Red Hat Design System for digital experiences gives designers and developers
       <figcaption>Designers</figcaption>
     </figure>
   </a>
-  <figure>
-    {% example
-      palette="descriptive",
-      alt="Card overlapping code editor user interface",
-      src="/assets/get-started/developers.png" %}
-    <figcaption>Developers (Coming soon)</figcaption>
-  </figure>
+  <a href="/get-started/developers">
+    <figure>
+      {% example
+        palette="descriptive",
+        alt="Card overlapping code editor user interface",
+        src="/assets/get-started/developers.png" %}
+      <figcaption>Developers</figcaption>
+    </figure>
+  </a>
 </nav>
 
 {% feedback %}

docs/get-started/designers.md

@@ -1,6 +1,7 @@
 ---
 layout: layout-basic.njk
 title: Designers
+heading: Designers
 order: 2
 tags:
   - getstarted

docs/get-started/developers/index.md

@@ -0,0 +1,52 @@
+---
+layout: layout-with-subnav.njk
+title: Overview
+heading: Developers
+tags:
+  - getstarted
+  - developers
+permalink: /get-started/developers/index.html
+subNavCollection: sortedDevelopers
+order: 00
+bodyClasses: element-docs
+---
+
+## Introduction
+
+Welcome to the **Red Hat Design System** (RHDS) for digital experiences. If you need to develop something using our design system, you have come to the right place.
+
+Read this section to get started and e-mail [[email protected]](mailto:[email protected]) or connect with us on Slack if you have any questions along the way.
+
+## Learn about our design system
+
+Our design system libraries and the documentation website offer assets and guidance needed to create digital experiences. Please use these resources to have a better understanding of how to use our design system.
+
+<div class="multi-column--min-400-wide">
+    <div>
+        <h3>Foundations</h3>
+        <p><a href="foundations">Foundations</a> are how we express our brand through color, space, typography, etc.</p>
+    </div>
+    <div>
+        <h3>Design tokens</h3>
+        <p><a href="tokens">Design tokens</a> are how we translate our design language decisions into code.</p>
+    </div>
+    <div>
+        <h3>Documentation</h3>
+        <p>This website offers guidance about how to use our <a href="elements">elements</a> and <a href="patterns">patterns</a> correctly.</p>
+    </div>
+    <div>
+        <h3>GitHub repositories</h3>
+        <p>Explore our code, roadmaps, and discussions in the <a href="https://github.com/RedHat-UX/red-hat-design-system">Red Hat Design System repo</a> and the <a href="https://github.com/RedHat-UX/red-hat-design-tokens">Red Hat Design Tokens repo</a>.</p>
+    </div>
+</div>
+
+## About web components
+
+Web components are based on a set of web platform APIs that help to create reusable and encapsulated UI elements. Those standards consist of custom elements, shadow DOM, and HTML Templates.
+
+Because they're able to work with any framework that supports HTML, web components can be used without having to rework all of your code and are less likely to be affected by changes in preferred web stacks. Encapsulation within the shadow DOM prevents a page's code from breaking a component's style and allows for a scalable design system.
+
+{% feedback %}
+  <h2>Designers</h2>
+  <p>To get started using our design system as a designer, go to the <a href="get-started/designers">Designers</a> page.</p>
+{% endfeedback %}

docs/get-started/developers/installation.md

@@ -0,0 +1,107 @@
+---
+layout: layout-with-subnav.njk
+title: Installation
+heading: Developers
+tags:
+  - developers
+permalink: /get-started/developers/installation/index.html
+subNavCollection: sortedDevelopers
+order: 10
+bodyClasses: element-docs
+---
+
+## How to install
+
+There are three ways you can install the Red Hat Design System's web components: CDN, NPM, or JSPM. Each element's "Code" page includes the same installation information with code snippets that are specific to that element.
+
+### Red Hat CDN
+
+{% alert title="CDN Prerelease",
+          state="warning" %}
+<p>We are currently working on our CDN, which will be soon moving into beta. This will be the preferred method of installation in the near future. If you are a Red Hat associate and have questions or comments about the CDN or installation process please connect with us on Slack.</p>
+{% endalert %}
+
+The recommended way to load RHDS is via the Red Hat Digital Experience CDN, and using an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap).
+
+If you have full control over the page you are using, add an import map to the `<head>`, pointing to the CDN, or update any existing import map. If you are not responsible for the page's `<head>`, request that the page owner makes the change on your behalf. 
+
+<rh-code-block>
+  <script type="text/sample-javascript">
+  <script type="importmap">
+    {
+      "imports": {
+        "@rhds/elements/": "https://www.redhatstatic.com/dx/v1-alpha/@rhds/[email protected]/elements/",
+        "@patternfly/elements/": "https://www.redhatstatic.com/dx/v1-alpha/@patternfly/[email protected]/"
+      }
+    }
+  <</script><script type="text/sample-javascript">/script>
+  </script>
+</rh-code-block>
+
+Once the import map is established, you can load the element with the following module, containing a [bare module specifier](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules). The example below shows how you'd load in <`rh-button>`.
+
+<rh-code-block>
+  <script type="text/sample-javascript">
+  <script type="module">
+    import '@rhds/elements/rh-button/rh-button.js';
+  <</script><script type="text/sample-javascript">/script>
+  </script>
+</rh-code-block>
+
+Note that modules may be placed in the `<head>`. Since they are deferred by default, they will not block rendering.
+
+### NPM
+
+Install RHDS using your team's preferred NPM package manager.
+
+<rh-code-block>
+  <script type="text/sample-javascript">
+  npm install @rhds/elements
+  </script>
+</rh-code-block>
+
+Once that's been accomplished, you will need to use a bundler to resolve the bare module specifiers and optionally optimize the package for your site's particular use case and needs. Comprehensive guides to bundling are beyond the scope of this page; read more about bundlers on their websites:
+
+- [Rollup](https://rollupjs.org/)
+- [esbuild](https://esbuild.github.io/)
+- [Parcel](https://parceljs.org/)
+- [Webpack](https://webpack.js.org/)
+
+### JSPM
+
+{% alert title="Public CDNs",
+          state="warning" %}
+<p>JSPM and other public CDNs should not be used on corporate domains. Use them for <strong>development purposes only</strong>!</p>
+{% endalert %}
+
+Add an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) to the `<head>`, pointing to the CDN, or update any existing import map.
+
+<rh-code-block>
+  <script type="text/sample-javascript">
+  <script type="importmap">
+    {
+    "imports": {
+      "@rhds/elements/": "https://jspm.dev/@rhds/elements/",
+      "@patternfly/elements/": "https://jspm.dev/@patternfly/elements/"
+      }
+    }
+  <</script><script type="text/sample-javascript">/script>
+  </script>
+</rh-code-block>
+
+Once the import map is established, you can load the element with the following module, containing a [bare module specifier](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules). The example below shows how you'd load in <`rh-button>`.
+
+<rh-code-block>
+  <script type="text/sample-javascript">
+  <script type="module">
+    import '@rhds/elements/rh-button/rh-button.js';
+  <</script><script type="text/sample-javascript">/script>
+  </script>
+</rh-code-block>
+
+Note that Modules may be placed in the `<head>`. Since they are deferred by default, they will not block rendering.
+
+{% feedback %}
+  <h2>Designers</h2>
+  <p>To get started using our design system as a designer, go to the <a href="get-started/designers">Designers</a> page.</p>
+{% endfeedback %}