⚓ Refresh glossary categories and doc card formatting

docs/data/analytics/hubble/analyst-guide/optimizing-queries.mdx

@@ -3,7 +3,7 @@ title: "Optimizing Queries"
 sidebar_position: 30
 ---
 
-Hubble has terabytes of data to explore—that’s a lot of data! With access to so much data at your fingertips, it is crucial to performance-tune your queries.
+Hubble has terabytes of data to explore—that’s a lot of data! With access to so much data at your fingertips, it is crucial to performance-tune your queries.
 
 One of the strengths of BigQuery is also its pitfall: you have access to tremendous compute capabilities, but you pay for what you use. If you fine-tune your queries, you will have access to powerful insights at the fraction of the cost of maintaining a data warehouse yourself. It is, however, easy to incur burdensome costs if you are not careful.
 

docs/data/analytics/hubble/data-catalog/data-dictionary/README.mdx

@@ -7,8 +7,4 @@ import DocCardList from "@theme/DocCardList";
 
 Hubble data is organized into bronze, silver, and gold sections.
 
-- Bronze 🥉 - raw, untransformed data from the Stellar network (e.g., history_contract_events contains all Stellar events)
-- Silver 🥈 - decoded, transformed, and filtered data (e.g., token_transfers contains SEP-41 complaint Stellar events)
-- Gold 🥇 - Curated analytics with friendly aggregate tables (e.g., tvl_agg aggregates the relevant amounts in Stellar events)
-
 <DocCardList />

docs/data/analytics/hubble/data-catalog/data-dictionary/bronze/_category_.json

@@ -0,0 +1,3 @@
+{
+  "description": "Raw, untransformed data from the Stellar network. For example, history_contract_events contains all Stellar events."
+}

docs/data/analytics/hubble/data-catalog/data-dictionary/gold/_category_.json

@@ -0,0 +1,3 @@
+{
+  "description": "Curated analytics with friendly aggregate tables. For example, tvl_agg aggregates relevant amounts in Stellar events."
+}

docs/data/analytics/hubble/data-catalog/data-dictionary/silver/_category_.json

@@ -0,0 +1,3 @@
+{
+  "description": "Decoded, transformed, and filtered data. For example, token_transfers_raw contains SEP-41-compliant Stellar events."
+}

docs/learn/fundamentals/contract-development/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Smart Contracts",
+  "position": 84,
+  "link": {
+    "type": "doc",
+    "id": "learn/fundamentals/contract-development/README"
+  },
+  "description": "Dive into Soroban smart-contract concepts, lifecycle guidance, and authorization patterns so you can ship production-ready code on Stellar."
+}

docs/learn/fundamentals/contract-development/storage/README.mdx

@@ -1,6 +1,7 @@
 ---
 title: Storage
 sidebar_position: 10
+description: Learn how smart contracts store and access data on Stellar, including persistent state and archival behavior.
 ---
 
 import DocCardList from "@theme/DocCardList";

docs/learn/fundamentals/contract-development/storage/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Storage",
+  "position": 10,
+  "link": {
+    "type": "doc",
+    "id": "learn/fundamentals/contract-development/storage/README"
+  }
+}

docs/learn/fundamentals/data-format/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Data Format",
+  "position": 85,
+  "link": {
+    "type": "doc",
+    "id": "learn/fundamentals/data-format/README"
+  },
+  "description": "Understand Stellar's XDR and JSON encodings so you can inspect transactions, debug payloads, and interchange data with other systems."
+}

docs/learn/fundamentals/stellar-data-structures/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Stellar Data Structures",
+  "position": 50,
+  "link": {
+    "type": "doc",
+    "id": "learn/fundamentals/stellar-data-structures/README"
+  },
+  "description": "Learn how accounts, assets, contracts, events, and ledgers fit together to describe everything living on the Stellar network."
+}

docs/learn/fundamentals/transactions/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Operations & Transactions",
+  "position": 60,
+  "link": {
+    "type": "doc",
+    "id": "learn/fundamentals/transactions/README"
+  },
+  "description": "Trace how Stellar transactions bundle operations, flow through the network, and unlock asset transfers or contract calls."
+}

docs/tokens/how-to-issue-an-asset.mdx

@@ -367,7 +367,7 @@ You can also create a market directly from the issuing account and issue tokens
 
 :::danger
 
-This section details how to lock your account with the purpose of limiting the supply of your issued asset. However, locking your account means you’ll never be able to do anything with it ever again—whether that’s adjusting signers, changing the home domain, claiming any held XLM, or any other operation. Your account will be completely frozen.
+This section details how to lock your account with the purpose of limiting the supply of your issued asset. However, locking your account means you’ll never be able to do anything with it ever again—whether that’s adjusting signers, changing the home domain, claiming any held XLM, or any other operation. Your account will be completely frozen.
 
 :::
 

src/theme/DocCard/index.tsx

@@ -0,0 +1,170 @@
+import React, {type ReactNode} from "react";
+import clsx from "clsx";
+import Link from "@docusaurus/Link";
+import {
+  useDocById,
+  useDocsVersion,
+  findFirstSidebarItemLink,
+} from "@docusaurus/plugin-content-docs/client";
+import type {
+  PropSidebarItemCategory,
+  PropSidebarItemLink,
+} from "@docusaurus/plugin-content-docs";
+import { usePluralForm } from "@docusaurus/theme-common";
+import isInternalUrl from "@docusaurus/isInternalUrl";
+import { translate } from "@docusaurus/Translate";
+
+import type { Props } from "@theme/DocCard";
+import Heading from "@theme/Heading";
+import styles from "./styles.module.scss";
+
+function useCategoryItemsPlural() {
+  const { selectMessage } = usePluralForm();
+  return (count: number) =>
+    selectMessage(
+      count,
+      translate(
+        {
+          message: "1 item|{count} items",
+          id: "theme.docs.DocCard.categoryDescription.plurals",
+          description:
+            "Default description for a category card in the generated index about how many items this category includes",
+        },
+        { count },
+      ),
+    );
+}
+
+function getStringCustomProp(
+  customProps: PropSidebarItemCategory["customProps"],
+  key: string,
+): string | undefined {
+  const value = customProps?.[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+function getCategoryIndexDocIds(href: string | undefined): string[] {
+  if (!href || !isInternalUrl(href)) {
+    return [];
+  }
+
+  const [pathname] = href.split(/[?#]/);
+  const pathSegments = pathname.replace(/^\/+|\/+$/g, "").split("/");
+  const docsSegmentIndex = pathSegments.indexOf("docs");
+  const docPathSegments =
+    docsSegmentIndex >= 0
+      ? pathSegments.slice(docsSegmentIndex + 1)
+      : pathSegments;
+  const docPath = docPathSegments.join("/");
+
+  return docPath ? [`${docPath}/README`, `${docPath}/index`, docPath] : [];
+}
+
+function CardContainer({
+  className,
+  href,
+  children,
+}: {
+  className?: string;
+  href: string;
+  children: ReactNode;
+}): ReactNode {
+  const linkProps = isInternalUrl(href) ? { to: href } : { href };
+
+  return (
+    <Link
+      {...linkProps}
+      className={clsx("card padding--lg", styles.cardContainer, className)}
+    >
+      {children}
+    </Link>
+  );
+}
+
+function CardLayout({
+  className,
+  href,
+  icon,
+  title,
+  description,
+}: {
+  className?: string;
+  href: string;
+  icon: ReactNode;
+  title: string;
+  description?: string;
+}): ReactNode {
+  return (
+    <CardContainer href={href} className={className}>
+      <Heading
+        as="h2"
+        className={clsx("text--truncate", styles.cardTitle)}
+        title={title}
+      >
+        <span aria-hidden="true">{icon}</span> {title}
+      </Heading>
+      {description && (
+        <p
+          className={styles.cardDescription}
+          title={description}
+        >
+          {description}
+        </p>
+      )}
+    </CardContainer>
+  );
+}
+
+function CardCategory({ item }: { item: PropSidebarItemCategory }): ReactNode {
+  const href = findFirstSidebarItemLink(item);
+  const categoryItemsPlural = useCategoryItemsPlural();
+  const { docs } = useDocsVersion();
+  const categoryIndexDoc = getCategoryIndexDocIds(item.href).find(
+    (docId) => docs[docId],
+  );
+
+  if (!href) {
+    return null;
+  }
+
+  const description =
+    item.description ??
+    getStringCustomProp(item.customProps, "description") ??
+    docs[categoryIndexDoc ?? ""]?.description ??
+    categoryItemsPlural(item.items.length);
+
+  return (
+    <CardLayout
+      className={item.className}
+      href={href}
+      icon="🗃️"
+      title={item.label}
+      description={description}
+    />
+  );
+}
+
+function CardLink({ item }: { item: PropSidebarItemLink }): ReactNode {
+  const icon = isInternalUrl(item.href) ? "📄" : "🔗";
+  const doc = useDocById(item.docId ?? undefined);
+  return (
+    <CardLayout
+      className={item.className}
+      href={item.href}
+      icon={icon}
+      title={item.label}
+      description={item.description ?? doc?.description}
+    />
+  );
+}
+
+export default function DocCard({ item }: Props): ReactNode {
+  switch (item.type) {
+    case "link":
+      return <CardLink item={item} />;
+    case "category":
+      return <CardCategory item={item} />;
+    default:
+      throw new Error(`Unknown DocCard item type: ${item.type}`);
+  }
+}

src/theme/DocCard/styles.module.scss

@@ -0,0 +1,36 @@
+.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 {
+  --card-description-lines: 4;
+
+  font-size: 0.8rem;
+  white-space: normal;
+  overflow-wrap: anywhere;
+  display: -webkit-box;
+  -webkit-line-clamp: var(--card-description-lines);
+  -webkit-box-orient: vertical;
+  max-height: calc(1.8em * var(--card-description-lines));
+  overflow: hidden;
+}