Refactor sidebar badges to use sidebar_custom_props

CLAUDE.md

@@ -2,10 +2,30 @@
 
 ## Hosting & URLs
 
-- Docs site is hosted on **Vercel** at `docs.marketdata.app`
-- Cloudflare rules proxy it to the public URL: `www.marketdata.app/docs/`
-- Staging is at `docs-staging.marketdata.app` → `www.marketdata.app/docs-staging/`
+- Docs site is hosted on **Cloudflare Pages** with a **Cloudflare Worker** reverse proxy
+- Worker (`worker/`) proxies `www.marketdata.app/docs/*` → `marketdata-docs.pages.dev`
+- Staging: `www.marketdata.app/docs-staging/*` → `marketdata-docs-staging.pages.dev`
+- CI/CD: GitHub Actions (`.github/workflows/deploy-docs.yml`) builds Docusaurus, restructures output to match URL paths, and deploys to Cloudflare Pages + Worker via Wrangler
+- Build output is restructured in CI to nest under `docs/` or `docs-staging/` so static files serve from correct paths without rewrite rules
+- Edge caching enabled on Worker subrequests; `_headers` file generated in CI for asset cache control
+
+## Workflow
+
+- Work on the **staging** branch, verify changes at `www.marketdata.app/docs-staging/`
+- Once verified, open a PR from `staging` → `main` and merge to deploy to production
 
 ## Package Manager
 
 - Use **yarn**, not npm (project uses `yarn.lock`)
+
+## Search
+
+- Algolia DocSearch (App ID: IUHZFO750H, Index: "Market Data Documentation")
+- Crawler config is managed in the Algolia dashboard, not in the codebase
+- `hierarchy.lvl1` is ranked above `hierarchy.lvl0` in searchable attributes (custom tweak from Docusaurus default)
+
+## Sidebar Badges
+
+- Badges (New, Premium, Beta, High Usage) are configured via `sidebar_custom_props: { badge: n/p/b/h }` in page frontmatter
+- Rendered by `src/theme/RenderTag.js`, styled in `src/css/custom.css`
+- Supported in sidebar links, sidebar categories, and page titles via swizzled theme components

README.md

@@ -1,29 +1,55 @@
 # Market Data Documentation
 
-This website is built using [Docusaurus 3](https://docusaurus.io/), a modern static website generator.
+The official documentation for [Market Data](https://www.marketdata.app/) — covering the REST API, SDKs, and Google Sheets Add-On. Built with [Docusaurus 3](https://docusaurus.io/).
 
-### Installation
-```
-$ yarn
-```
-### Local Development
-```
-$ yarn start
-```
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
-### Build
-```
-$ yarn build
-```
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
-### Deployment
-Using SSH:
-```
-$ USE_SSH=true yarn deploy
+**Production:** [www.marketdata.app/docs/](https://www.marketdata.app/docs/)
+**Staging:** [www.marketdata.app/docs-staging/](https://www.marketdata.app/docs-staging/)
+
+## Documentation Sections
+
+| Section | Path | Description |
+|---------|------|-------------|
+| **API** | `/api` | REST API reference — stocks, options, indices, funds, markets, and utilities |
+| **SDKs** | `/sdk` | Client libraries for Go, Python, and PHP |
+| **Sheets Add-On** | `/sheets` | Google Sheets Add-On documentation |
+| **Accounts & Billing** | `/account` | Account management, plans, billing, and entitlements |
+
+## Local Development
+
+```bash
+yarn          # Install dependencies
+yarn start    # Start dev server at localhost:3000
+yarn build    # Production build
 ```
-Not using SSH:
+
+## Deployment
+
+The site is hosted on **Cloudflare Pages** with a **Cloudflare Worker** reverse proxy. Deployment is fully automated via GitHub Actions.
+
+1. Push to `staging` — deploys to the staging site
+2. Verify changes at the staging URL
+3. Open a PR from `staging` → `main` and merge — deploys to production
+
+The CI pipeline (`.github/workflows/deploy-docs.yml`) builds the Docusaurus site, restructures the output to match the `/docs/` and `/docs-staging/` URL paths, generates cache headers, and deploys via Wrangler.
+
+## Project Structure
+
 ```
-$ GIT_USER=<Your GitHub username> yarn deploy
+api/              # API reference docs (MDX)
+sdk/              # SDK docs — Go, Python, PHP (MDX)
+sheets/           # Google Sheets Add-On docs (MDX)
+account/          # Account & billing docs (MDX)
+src/
+  theme/          # Swizzled Docusaurus theme components
+  css/            # Custom styles
+worker/           # Cloudflare Worker reverse proxy
+.github/workflows # CI/CD pipeline
 ```
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
 
+## Search
+
+Search is powered by [Algolia DocSearch](https://docsearch.algolia.com/). The crawler configuration is managed in the Algolia dashboard, not in this repository.
+
+## License
+
+MIT

api/funds/candles.mdx

@@ -1,6 +1,8 @@
 ---
-title: Candles tg n
+title: Candles
 sidebar_position: 1
+sidebar_custom_props:
+  badge: n
 ---
 
 import Tabs from "@theme/Tabs";

api/options/quotes.mdx

@@ -1,8 +1,10 @@
 ---
-title: Quotes tg h
+title: Quotes
 sidebar_position: 4
 tags:
   - "API: High Usage"
+sidebar_custom_props:
+  badge: h
 ---
 
 Get a current or historical end of day quote for a single options contract.

api/stocks/earnings.mdx

@@ -1,8 +1,10 @@
 ---
-title: Earnings tg p
+title: Earnings
 sidebar_position: 4
 tags:
   - "API: Premium"
+sidebar_custom_props:
+  badge: p
 ---
 
 Get historical earnings per share data or a future earnings calendar for a stock.

api/stocks/news.mdx

@@ -1,8 +1,10 @@
 ---
-title: News tg b
+title: News
 sidebar_position: 5
 tags:
   - "API: Beta"
+sidebar_custom_props:
+  badge: b
 ---
 
 :::warning Beta Endpoint

api/stocks/prices.mdx

@@ -1,8 +1,10 @@
 ---
-title: Real-Time Prices tg h
+title: Real-Time Prices
 sidebar_position: 1
 tags:
   - "API: High Usage"
+sidebar_custom_props:
+  badge: h
 ---
 
 Get real-time midpoint prices for one or more stocks. This endpoint returns real-time prices for stocks, using the [SmartMid](https://www.marketdata.app/smart-mid/) model.

api/utilities/status.mdx

@@ -1,6 +1,8 @@
 ---
-title: API Status tg n
+title: API Status
 sidebar_position: 1
+sidebar_custom_props:
+  badge: n
 ---
 
 import Tabs from "@theme/Tabs";

sdk/php/index.mdx

@@ -2,6 +2,8 @@
 title: PHP SDK
 sidebar_position: 4
 slug: /php
+sidebar_custom_props:
+  badge: n
 ---
 
 Welcome to the Market Data PHP SDK documentation. This SDK allows you to easily integrate Market Data services into your PHP applications.

sdk/py/index.mdx

@@ -2,6 +2,8 @@
 title: Python SDK
 sidebar_position: 3
 slug: /py
+sidebar_custom_props:
+  badge: n
 ---
 
 Welcome to the Market Data Python SDK documentation. This SDK allows you to easily integrate Market Data services into your Python applications.

src/theme/DocBreadcrumbs/index.js

@@ -11,15 +11,13 @@ import { translate } from "@docusaurus/Translate";
 import HomeBreadcrumbItem from "@theme/DocBreadcrumbs/Items/Home";
 import EditThisPage from "@theme/EditThisPage";
 import styles from "./styles.module.css";
-import { getLabelAndTag } from "@site/src/utils/functions";
 // TODO move to design system folder
 function BreadcrumbsItemLink({ children, href, isLast }) {
-  let { label, tag } = getLabelAndTag({ label: children });
   const className = "breadcrumbs__link";
   if (isLast) {
     return (
       <span className={className} itemProp="name">
-        {label}
+        {children}
       </span>
     );
   }
@@ -60,7 +58,7 @@ export default function DocBreadcrumbs() {
   const { editUrl } = metadata;
   const windowSize = useWindowSize();
   const isDesktop = windowSize === "desktop" || windowSize === "ssr";
-  
+
   if (!breadcrumbs) {
     return null;
   }

src/theme/DocCard/index.js

@@ -9,7 +9,6 @@ import isInternalUrl from "@docusaurus/isInternalUrl";
 import { translate } from "@docusaurus/Translate";
 import Heading from "@theme/Heading";
 import styles from "./styles.module.css";
-import { getLabelAndTag } from "@site/src/utils/functions";
 function CardContainer({ href, children }) {
   return (
     <Link
@@ -20,14 +19,13 @@ function CardContainer({ href, children }) {
   );
 }
 function CardLayout({ href, icon, title, description }) {
-  let { label, tag } = getLabelAndTag({ label: title || "" });
   return (
     <CardContainer href={href}>
       <Heading
         as="h2"
         className={clsx("text--truncate", styles.cardTitle)}
-        title={label}>
-        {icon} {label}
+        title={title}>
+        {icon} {title}
       </Heading>
       {description && (
         <p

src/theme/DocItem/Content/index.js

@@ -5,7 +5,6 @@ import { useDoc } from "@docusaurus/theme-common/internal";
 import Heading from "@theme/Heading";
 import MDXContent from "@theme/MDXContent";
 import RenderTag from "../../RenderTag";
-import { getLabelAndTag } from "@site/src/utils/functions";
 /**
  Title can be declared inside md content or declared through
  front matter and added manually. To make both cases consistent,
@@ -27,7 +26,8 @@ function useSyntheticTitle() {
 }
 export default function DocItemContent({ children }) {
   const syntheticTitle = useSyntheticTitle();
-  let { label, tag } = getLabelAndTag({ label: syntheticTitle || "" });
+  const { frontMatter } = useDoc();
+  const badge = frontMatter.sidebar_custom_props?.badge;
   return (
     <div className={clsx(ThemeClassNames.docs.docMarkdown, "markdown")}>
       {syntheticTitle && (
@@ -38,7 +38,7 @@ export default function DocItemContent({ children }) {
               alignItems: "center",
               display: "flex",
             }}>
-            {`${label} `}
+            {`${syntheticTitle} `}
             <div
               style={{
                 height: "100%",
@@ -47,7 +47,7 @@ export default function DocItemContent({ children }) {
                 justifyContent: "center",
                 paddingTop: 7,
               }}>
-              <RenderTag tag={tag} />
+              <RenderTag tag={badge} />
             </div>
           </Heading>
         </header>

src/theme/DocItem/Metadata/index.js

@@ -1,14 +1,12 @@
 import React from "react";
 import { PageMetadata } from "@docusaurus/theme-common";
 import { useDoc } from "@docusaurus/theme-common/internal";
-import { getLabelAndTag } from "@site/src/utils/functions";
 
 export default function DocItemMetadata() {
   const { metadata, frontMatter, assets } = useDoc();
-  let { label, tag } = getLabelAndTag({ label: metadata.title || "" });
   return (
     <PageMetadata
-      title={label}
+      title={metadata.title}
       description={metadata.description}
       keywords={frontMatter.keywords}
       image={assets.image ?? frontMatter.image}

src/theme/DocSidebarItem/Category/index.js

@@ -17,6 +17,7 @@ import Link from '@docusaurus/Link';
 import {translate} from '@docusaurus/Translate';
 import useIsBrowser from '@docusaurus/useIsBrowser';
 import DocSidebarItems from '@theme/DocSidebarItems';
+import RenderTag from '../../RenderTag';
 // If we navigate to a category and it becomes active, it should automatically
 // expand itself
 function useAutoExpandActiveCategory({isActive, collapsed, updateCollapsed}) {
@@ -86,7 +87,8 @@ export default function DocSidebarItemCategory({
   index,
   ...props
 }) {
-  const {items, label, collapsible, className, href} = item;
+  const {items, label, collapsible, className, href, customProps} = item;
+  const badge = customProps?.badge;
   const {
     docs: {
       sidebar: {autoCollapseCategories},
@@ -163,6 +165,7 @@ export default function DocSidebarItemCategory({
           href={collapsible ? hrefWithSSRFallback ?? '#' : hrefWithSSRFallback}
           {...props}>
           {label}
+          <RenderTag size="small" tag={badge} />
         </Link>
         {href && collapsible && (
           <CollapseButton

src/theme/DocSidebarItem/Link/index.js

@@ -7,7 +7,6 @@ import isInternalUrl from "@docusaurus/isInternalUrl";
 import IconExternalLink from "@theme/Icon/ExternalLink";
 import styles from "./styles.module.css";
 import RenderTag from "../../RenderTag";
-import { getLabelAndTag } from "@site/src/utils/functions";
 
 export default function DocSidebarItemLink({
   item,
@@ -17,13 +16,10 @@ export default function DocSidebarItemLink({
   index,
   ...props
 }) {
-  let { href, label, className, autoAddBaseUrl } = item;
-  const labelTag = getLabelAndTag({ label });
-  label = labelTag.label;
-  const tag = labelTag.tag;
+  const { href, label, className, autoAddBaseUrl, customProps } = item;
+  const badge = customProps?.badge;
   const isActive = isActiveSidebarItem(item, activePath);
   const isInternalLink = isInternalUrl(href);
-  // const { metadata, frontMatter, contentTitle } = useDoc();
   return (
     <li
       className={clsx(
@@ -49,7 +45,7 @@ export default function DocSidebarItemLink({
         })}
         {...props}>
         {label}
-        <RenderTag size="small" tag={tag} />
+        <RenderTag size="small" tag={badge} />
         {!isInternalLink && <IconExternalLink />}
       </Link>
     </li>

src/theme/PaginatorNavLink/index.js

@@ -1,10 +1,8 @@
 import React from "react";
 import clsx from "clsx";
 import Link from "@docusaurus/Link";
-import { getLabelAndTag } from "@site/src/utils/functions";
 export default function PaginatorNavLink(props) {
   const { permalink, title, subLabel, isNext } = props;
-  let { label, tag } = getLabelAndTag({ label: title || "" });
   return (
     <Link
       className={clsx(
@@ -13,7 +11,7 @@ export default function PaginatorNavLink(props) {
       )}
       to={permalink}>
       {subLabel && <div className="pagination-nav__sublabel">{subLabel}</div>}
-      <div className="pagination-nav__label">{label}</div>
+      <div className="pagination-nav__label">{title}</div>
     </Link>
   );
 }