diff --git a/docs/data/analytics/hubble/analyst-guide/optimizing-queries.mdx b/docs/data/analytics/hubble/analyst-guide/optimizing-queries.mdx index 5f73d739e9..59cb2d811a 100644 --- a/docs/data/analytics/hubble/analyst-guide/optimizing-queries.mdx +++ b/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. diff --git a/docs/data/analytics/hubble/data-catalog/data-dictionary/README.mdx b/docs/data/analytics/hubble/data-catalog/data-dictionary/README.mdx index 651f2d4c2a..5711d1d9ad 100644 --- a/docs/data/analytics/hubble/data-catalog/data-dictionary/README.mdx +++ b/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) - diff --git a/docs/data/analytics/hubble/data-catalog/data-dictionary/bronze/_category_.json b/docs/data/analytics/hubble/data-catalog/data-dictionary/bronze/_category_.json new file mode 100644 index 0000000000..bb96482b8c --- /dev/null +++ b/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." +} diff --git a/docs/data/analytics/hubble/data-catalog/data-dictionary/gold/_category_.json b/docs/data/analytics/hubble/data-catalog/data-dictionary/gold/_category_.json new file mode 100644 index 0000000000..4e28ff12f7 --- /dev/null +++ b/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." +} diff --git a/docs/data/analytics/hubble/data-catalog/data-dictionary/silver/_category_.json b/docs/data/analytics/hubble/data-catalog/data-dictionary/silver/_category_.json new file mode 100644 index 0000000000..b160b56ded --- /dev/null +++ b/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." +} diff --git a/docs/learn/fundamentals/contract-development/_category_.json b/docs/learn/fundamentals/contract-development/_category_.json new file mode 100644 index 0000000000..421dc264c5 --- /dev/null +++ b/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." +} diff --git a/docs/learn/fundamentals/contract-development/storage/README.mdx b/docs/learn/fundamentals/contract-development/storage/README.mdx index 84004720be..d7e9f2b032 100644 --- a/docs/learn/fundamentals/contract-development/storage/README.mdx +++ b/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"; diff --git a/docs/learn/fundamentals/contract-development/storage/_category_.json b/docs/learn/fundamentals/contract-development/storage/_category_.json new file mode 100644 index 0000000000..e0748c9e35 --- /dev/null +++ b/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" + } +} diff --git a/docs/learn/fundamentals/data-format/_category_.json b/docs/learn/fundamentals/data-format/_category_.json new file mode 100644 index 0000000000..bba43ef4d4 --- /dev/null +++ b/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." +} diff --git a/docs/learn/fundamentals/stellar-data-structures/_category_.json b/docs/learn/fundamentals/stellar-data-structures/_category_.json new file mode 100644 index 0000000000..5d21b285a4 --- /dev/null +++ b/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." +} diff --git a/docs/learn/fundamentals/transactions/_category_.json b/docs/learn/fundamentals/transactions/_category_.json new file mode 100644 index 0000000000..4bb739336d --- /dev/null +++ b/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." +} diff --git a/docs/tokens/how-to-issue-an-asset.mdx b/docs/tokens/how-to-issue-an-asset.mdx index f184b07984..9b9dfd0a1c 100644 --- a/docs/tokens/how-to-issue-an-asset.mdx +++ b/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. ::: diff --git a/src/theme/DocCard/index.tsx b/src/theme/DocCard/index.tsx new file mode 100644 index 0000000000..d71d323b52 --- /dev/null +++ b/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 ( + + {children} + + ); +} + +function CardLayout({ + className, + href, + icon, + title, + description, +}: { + className?: string; + href: string; + icon: ReactNode; + title: string; + description?: string; +}): ReactNode { + return ( + + + {title} + + {description && ( +

+ {description} +

+ )} + + ); +} + +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 ( + + ); +} + +function CardLink({ item }: { item: PropSidebarItemLink }): ReactNode { + const icon = isInternalUrl(item.href) ? "📄" : "🔗"; + const doc = useDocById(item.docId ?? undefined); + return ( + + ); +} + +export default function DocCard({ item }: Props): ReactNode { + switch (item.type) { + case "link": + return ; + case "category": + return ; + default: + throw new Error(`Unknown DocCard item type: ${item.type}`); + } +} diff --git a/src/theme/DocCard/styles.module.scss b/src/theme/DocCard/styles.module.scss new file mode 100644 index 0000000000..ae93f8d665 --- /dev/null +++ b/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; +}