add docs index page (#94)

* add docs index page

* improve DocCardList styles

* adjust styles of docs index

.gitignore

@@ -20,4 +20,5 @@ yarn-debug.log*
 yarn-error.log*
 
 /opentf-repo
-/docs
+/docs/**
+!/docs/index.mdx

docs/index.mdx

@@ -0,0 +1,43 @@
+---
+title: Home
+hide_table_of_contents: true
+---
+
+import DocCardList from "@theme/DocCardList";
+
+### Documentation
+
+The documentation is divided into four main sections, covering CLI-based workflows, internal processes, an introduction to the tool's capabilities, and guidance on using the OpenTofu configuration language for managing infrastructure.
+
+<DocCardList
+  items={[
+    {
+      type: "link",
+      href: "/docs/cli",
+      label: "CLI Documentation",
+      description:
+        "Learn OpenTofu's CLI-based workflows. You can use the CLI alone or with cloud backends.",
+    },
+    {
+      type: "link",
+      href: "/docs/internals",
+      label: "Internals",
+      description:
+        "Learn how OpenTofu generates the resource dependency graph and executes other internal processes.",
+    },
+    {
+      type: "link",
+      href: "/docs/intro",
+      label: "Intro",
+      description:
+        "OpenTofu is an infrastructure as code tool that lets you build, change, and version cloud and on-prem resources safely and efficiently.",
+    },
+    {
+      type: "link",
+      href: "/docs/language",
+      label: "Language",
+      description:
+        "Use the OpenTF configuration language to describe the infrastructure that OpenTF manages.",
+    },
+  ]}
+/>

src/css/custom.css

@@ -22,6 +22,7 @@ html[data-theme="dark"] {
   --ifm-navbar-search-input-icon: url('data:image/svg+xml;utf8,<svg fill="%239DA6B5" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" height="16px" width="16px"><path d="M6.02945,10.20327a4.17382,4.17382,0,1,1,4.17382-4.17382A4.15609,4.15609,0,0,1,6.02945,10.20327Zm9.69195,4.2199L10.8989,9.59979A5.88021,5.88021,0,0,0,12.058,6.02856,6.00467,6.00467,0,1,0,9.59979,10.8989l4.82338,4.82338a.89729.89729,0,0,0,1.29912,0,.89749.89749,0,0,0-.00087-1.29909Z" /></svg>');
   --ifm-font-color-base: theme("colors.gray.50");
   --ifm-navbar-search-input-placeholder-color: theme("colors.gray.500");
+  --ifm-card-background-color: theme("colors.blue.900");
 }
 
 html[data-theme="light"] {
@@ -31,6 +32,7 @@ html[data-theme="light"] {
   --ifm-navbar-search-input-icon: url('data:image/svg+xml;utf8,<svg fill="%238590A2" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" height="16px" width="16px"><path d="M6.02945,10.20327a4.17382,4.17382,0,1,1,4.17382-4.17382A4.15609,4.15609,0,0,1,6.02945,10.20327Zm9.69195,4.2199L10.8989,9.59979A5.88021,5.88021,0,0,0,12.058,6.02856,6.00467,6.00467,0,1,0,9.59979,10.8989l4.82338,4.82338a.89729.89729,0,0,0,1.29912,0,.89749.89749,0,0,0-.00087-1.29909Z" /></svg>');
   --ifm-font-color-base: theme("colors.gray.900");
   --ifm-navbar-search-input-placeholder-color: theme("colors.gray.600");
+  --ifm-card-background-color: theme("colors.white");
 }
 
 body {

src/theme/DocCard/index.js

@@ -0,0 +1,92 @@
+import React from "react";
+import clsx from "clsx";
+import Link from "@docusaurus/Link";
+import {
+  findFirstCategoryLink,
+  useDocById,
+} from "@docusaurus/theme-common/internal";
+import isInternalUrl from "@docusaurus/isInternalUrl";
+import { translate } from "@docusaurus/Translate";
+import styles from "./styles.module.css";
+function CardContainer({ href, children }) {
+  return (
+    <Link
+      href={href}
+      className={clsx(
+        "card padding--lg",
+        "rounded-none text-gray-800 dark:text-gray-100 hover:text-gray-900 hover:dark:text-gray-50",
+        styles.cardContainer
+      )}
+    >
+      {children}
+    </Link>
+  );
+}
+function CardLayout({ href, icon, title, description }) {
+  return (
+    <CardContainer href={href}>
+      <h2
+        className={clsx("text--truncate", styles.cardTitle, "mb-4")}
+        title={title}
+      >
+        {title}
+      </h2>
+      {description && (
+        <p
+          className={clsx(styles.cardDescription, "line-clamp-2")}
+          title={description}
+        >
+          {description}
+        </p>
+      )}
+    </CardContainer>
+  );
+}
+function CardCategory({ item }) {
+  const href = findFirstCategoryLink(item);
+  // Unexpected: categories that don't have a link have been filtered upfront
+  if (!href) {
+    return null;
+  }
+  return (
+    <CardLayout
+      href={href}
+      icon="🗃️"
+      title={item.label}
+      description={
+        item.description ??
+        translate(
+          {
+            message: "{count} items",
+            id: "theme.docs.DocCard.categoryDescription",
+            description:
+              "The default description for a category card in the generated index about how many items this category includes",
+          },
+          { count: item.items.length }
+        )
+      }
+    />
+  );
+}
+function CardLink({ item }) {
+  const icon = isInternalUrl(item.href) ? "📄️" : "🔗";
+  const doc = useDocById(item.docId ?? undefined);
+  return (
+    <CardLayout
+      href={item.href}
+      icon={icon}
+      title={item.label}
+      description={item.description ?? doc?.description}
+    />
+  );
+}
+export default function DocCard({ item }) {
+  switch (item.type) {
+    case "link":
+      return <CardLink item={item} />;
+    case "category":
+      return <CardCategory item={item} />;
+    default:
+      throw new Error(`unknown item type ${JSON.stringify(item)}`);
+  }
+}

src/theme/DocCard/styles.module.css

@@ -0,0 +1,27 @@
+.cardContainer {
+  --ifm-link-color: var(--ifm-color-emphasis-800);
+  --ifm-link-hover-color: var(--ifm-color-emphasis-700);
+  --ifm-link-hover-decoration: none;
+
+  box-shadow: 0 1.5px 3px 0 rgb(0 0 0 / 15%);
+  border: 1px solid var(--ifm-color-emphasis-200);
+  transition: all var(--ifm-transition-fast) ease;
+  transition-property: border, box-shadow;
+}
+
+.cardContainer:hover {
+  border-color: var(--ifm-color-primary);
+  box-shadow: 0 3px 6px 0 rgb(0 0 0 / 20%);
+}
+
+.cardContainer *:last-child {
+  margin-bottom: 0;
+}
+
+.cardTitle {
+  font-size: 1.2rem;
+}
+
+.cardDescription {
+  font-size: 0.8rem;
+}

src/theme/DocCardList/index.js

@@ -0,0 +1,32 @@
+import React from "react";
+import clsx from "clsx";
+import {
+  useCurrentSidebarCategory,
+  filterDocCardListItems,
+} from "@docusaurus/theme-common";
+import DocCard from "@theme/DocCard";
+function DocCardListForCurrentSidebarCategory({ className }) {
+  const category = useCurrentSidebarCategory();
+  return <DocCardList items={category.items} className={className} />;
+}
+export default function DocCardList(props) {
+  const { items, className } = props;
+  if (!items) {
+    return <DocCardListForCurrentSidebarCategory {...props} />;
+  }
+  const filteredItems = filterDocCardListItems(items);
+  return (
+    <section
+      className={clsx(
+        "grid grid-cols-1 md:grid-cols-2 gap-4 md:gap-6 w-full",
+        className
+      )}
+    >
+      {filteredItems.map((item, index) => (
+        <article key={index} className="not-prose">
+          <DocCard item={item} />
+        </article>
+      ))}
+    </section>
+  );
+}