From f9a37d9738d5c94fd6f7c72cd3618e25b0a37817 Mon Sep 17 00:00:00 2001 From: maxnorm Date: Fri, 5 Jun 2026 17:23:53 -0400 Subject: [PATCH 1/8] improve meta data --- website/docs/contribution/cli/templates.mdx | 2 +- website/docs/contribution/code-style-guide.mdx | 2 +- website/docs/contribution/how-to-contribute.mdx | 2 +- website/docs/contribution/testing.mdx | 2 +- website/docs/design/banned-solidity-features.mdx | 2 +- website/docs/design/design-for-composition.mdx | 2 +- website/docs/design/index.mdx | 2 +- website/docs/design/maintain-compatibility.mdx | 2 +- website/docs/design/repeat-yourself.mdx | 2 +- website/docs/design/written-to-be-read.mdx | 2 +- website/docs/foundations/composable-facets.mdx | 2 +- website/docs/foundations/custom-facets.mdx | 2 +- website/docs/foundations/diamond-contracts.mdx | 2 +- website/docs/foundations/facets-and-modules.mdx | 2 +- website/docs/foundations/index.mdx | 2 +- website/docs/foundations/onchain-contract-library.mdx | 2 +- website/docs/foundations/reusable-facet-logic.mdx | 2 +- website/docs/foundations/solidity-modules.mdx | 2 +- website/docs/getting-started/installation.md | 2 ++ website/docs/intro.mdx | 2 +- website/docs/library/access/index.mdx | 2 +- website/docs/library/diamond/index.mdx | 2 +- website/docs/library/index.mdx | 2 +- website/docusaurus.config.js | 1 + website/src/pages/index.js | 2 +- 25 files changed, 26 insertions(+), 23 deletions(-) diff --git a/website/docs/contribution/cli/templates.mdx b/website/docs/contribution/cli/templates.mdx index 38867f18..604915b0 100644 --- a/website/docs/contribution/cli/templates.mdx +++ b/website/docs/contribution/cli/templates.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 3 -title: New Project Templates +title: "CLI Project Templates" description: How to add new project templates to the Compose CLI and keep the template registry in sync. --- diff --git a/website/docs/contribution/code-style-guide.mdx b/website/docs/contribution/code-style-guide.mdx index 1ca41b69..9523eea3 100644 --- a/website/docs/contribution/code-style-guide.mdx +++ b/website/docs/contribution/code-style-guide.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 3 -title: Code Style Guide +title: "Code Style Guide — Solidity Conventions" description: Code style guidelines for developing Compose facets and modules --- diff --git a/website/docs/contribution/how-to-contribute.mdx b/website/docs/contribution/how-to-contribute.mdx index 1f1c576a..2e3144cb 100644 --- a/website/docs/contribution/how-to-contribute.mdx +++ b/website/docs/contribution/how-to-contribute.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 1 -title: How to Contribute +title: "How to Contribute to Compose" description: Learn how to contribute to Compose --- diff --git a/website/docs/contribution/testing.mdx b/website/docs/contribution/testing.mdx index 485c89be..d34881a6 100644 --- a/website/docs/contribution/testing.mdx +++ b/website/docs/contribution/testing.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 4 -title: Testing +title: "Testing — Behavior-First with Foundry" description: Compose tests are **behavior-first** and primarily written with Foundry fuzz tests. --- diff --git a/website/docs/design/banned-solidity-features.mdx b/website/docs/design/banned-solidity-features.mdx index d48a1a5c..3188f15b 100644 --- a/website/docs/design/banned-solidity-features.mdx +++ b/website/docs/design/banned-solidity-features.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 4 -title: Banned Solidity Features +title: "Banned Solidity Features" description: Solidity language features that are banned from Compose facets and modules. --- diff --git a/website/docs/design/design-for-composition.mdx b/website/docs/design/design-for-composition.mdx index 03ec0e48..310d192e 100644 --- a/website/docs/design/design-for-composition.mdx +++ b/website/docs/design/design-for-composition.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 5 -title: Design for Composition +title: "Design for Composition — Guidelines & Rules" description: How to design Compose facets and modules for composition. --- diff --git a/website/docs/design/index.mdx b/website/docs/design/index.mdx index 4cd415a7..0cfe0561 100644 --- a/website/docs/design/index.mdx +++ b/website/docs/design/index.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 1 -title: Compose Design +title: "Design Principles" description: Overview for how Compose is designed sidebar_class_name: hidden --- diff --git a/website/docs/design/maintain-compatibility.mdx b/website/docs/design/maintain-compatibility.mdx index 445b67ed..c3ceecff 100644 --- a/website/docs/design/maintain-compatibility.mdx +++ b/website/docs/design/maintain-compatibility.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 6 -title: Maintain Compatibility +title: "Maintain Compatibility — Standards & Interoperability" description: Maintain compatibility with existing standards, libraries, and systems --- diff --git a/website/docs/design/repeat-yourself.mdx b/website/docs/design/repeat-yourself.mdx index b7ab7676..4f488168 100644 --- a/website/docs/design/repeat-yourself.mdx +++ b/website/docs/design/repeat-yourself.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 3 -title: Repeat Yourself +title: "Repeat Yourself — Intentional Code Duplication" description: Repeat yourself when it makes your code easier to read and understand. --- diff --git a/website/docs/design/written-to-be-read.mdx b/website/docs/design/written-to-be-read.mdx index d6c2b759..75964c52 100644 --- a/website/docs/design/written-to-be-read.mdx +++ b/website/docs/design/written-to-be-read.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 2 -title: Compose Is Written to Be Read +title: "Written to Be Read — Code Readability First" description: Compose is written to be read by other developers. --- diff --git a/website/docs/foundations/composable-facets.mdx b/website/docs/foundations/composable-facets.mdx index 823693e6..c568bc58 100644 --- a/website/docs/foundations/composable-facets.mdx +++ b/website/docs/foundations/composable-facets.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 6 -title: Composable Facets +title: "Composable Facets — Modular Building Blocks" description: Mix and match facets to build complex systems from simple, interoperable building blocks. --- diff --git a/website/docs/foundations/custom-facets.mdx b/website/docs/foundations/custom-facets.mdx index 42421c31..502205e5 100644 --- a/website/docs/foundations/custom-facets.mdx +++ b/website/docs/foundations/custom-facets.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 8 -title: "Custom Functionality: Compose Your Own Facets" +title: "Custom Facets — Build Your Own" description: "Build your own facets that work seamlessly with existing Compose Functionality." --- diff --git a/website/docs/foundations/diamond-contracts.mdx b/website/docs/foundations/diamond-contracts.mdx index fa112367..c3e099e7 100644 --- a/website/docs/foundations/diamond-contracts.mdx +++ b/website/docs/foundations/diamond-contracts.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 2 -title: Diamond Contracts +title: "Diamond Contracts — Facets, Storage & Delegation" description: "Understand Diamonds from the ground up—facets, storage, delegation, and how Compose uses them." --- diff --git a/website/docs/foundations/facets-and-modules.mdx b/website/docs/foundations/facets-and-modules.mdx index c0b35f11..f32f64e8 100644 --- a/website/docs/foundations/facets-and-modules.mdx +++ b/website/docs/foundations/facets-and-modules.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 7 -title: "Understanding Facets and Modules" +title: "Facets and Modules — How They Work Together" description: Learn how facets and modules work together through shared storage to build composable systems. --- diff --git a/website/docs/foundations/index.mdx b/website/docs/foundations/index.mdx index 45a8b489..3d170997 100644 --- a/website/docs/foundations/index.mdx +++ b/website/docs/foundations/index.mdx @@ -1,5 +1,5 @@ --- -title: Foundations +title: "Foundations — Core Concepts" description: Compose smart contracts are designed to be composable. sidebar_class_name: hidden --- diff --git a/website/docs/foundations/onchain-contract-library.mdx b/website/docs/foundations/onchain-contract-library.mdx index 53a6a971..4956fc05 100644 --- a/website/docs/foundations/onchain-contract-library.mdx +++ b/website/docs/foundations/onchain-contract-library.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 4 -title: On-chain Library +title: "On-chain Contract Library" description: Compose provides a set of reusable on-chain contracts that already exist on blockchains --- diff --git a/website/docs/foundations/reusable-facet-logic.mdx b/website/docs/foundations/reusable-facet-logic.mdx index fc511550..6c0231c3 100644 --- a/website/docs/foundations/reusable-facet-logic.mdx +++ b/website/docs/foundations/reusable-facet-logic.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 5 -title: Reusable Logic +title: "Reusable Facet Logic — Deploy Once, Reuse Everywhere" description: Deploy once, reuse everywhere. Compose facets are shared across thousands of projects. --- diff --git a/website/docs/foundations/solidity-modules.mdx b/website/docs/foundations/solidity-modules.mdx index 4a6a18d4..4124d47c 100644 --- a/website/docs/foundations/solidity-modules.mdx +++ b/website/docs/foundations/solidity-modules.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 3 -title: Solidity Modules +title: "Solidity Modules — Reusable Logic Outside Contracts" description: What Solidity modules are, how they differ from contracts and libraries, and how Compose uses them for reusable facet logic and shared storage. --- diff --git a/website/docs/getting-started/installation.md b/website/docs/getting-started/installation.md index 526b0c1f..6dd93fcc 100644 --- a/website/docs/getting-started/installation.md +++ b/website/docs/getting-started/installation.md @@ -1,5 +1,7 @@ --- sidebar_position: 1 +title: "Installation" +description: "Get up and running with Compose in just a few minutes." --- import DocSubtitle from '@site/src/components/docs/DocSubtitle'; diff --git a/website/docs/intro.mdx b/website/docs/intro.mdx index 8b9deec5..3fdf785c 100644 --- a/website/docs/intro.mdx +++ b/website/docs/intro.mdx @@ -1,7 +1,7 @@ --- sidebar_position: 1 slug: / -title: "Introduction" +title: "Smart Contract Library for ERC-2535 / ERC-8153 Diamonds" description: Compose is a smart contract library for building smart contract systems using the ERC-2535 Diamond standard. --- diff --git a/website/docs/library/access/index.mdx b/website/docs/library/access/index.mdx index bc27733a..cb670a07 100644 --- a/website/docs/library/access/index.mdx +++ b/website/docs/library/access/index.mdx @@ -1,5 +1,5 @@ --- -title: "Access Control" +title: "Access Control — Diamond Permission Management" description: "Access control patterns for permission management in Compose diamonds." --- diff --git a/website/docs/library/diamond/index.mdx b/website/docs/library/diamond/index.mdx index 65758b08..0e79cbc9 100644 --- a/website/docs/library/diamond/index.mdx +++ b/website/docs/library/diamond/index.mdx @@ -1,5 +1,5 @@ --- -title: "Diamond Core" +title: "Diamond Core — Proxy Functionality" description: "Core diamond proxy functionality for ERC-2535 diamonds." --- diff --git a/website/docs/library/index.mdx b/website/docs/library/index.mdx index 106b7077..37feb0e1 100644 --- a/website/docs/library/index.mdx +++ b/website/docs/library/index.mdx @@ -1,5 +1,5 @@ --- -title: "Library" +title: "On-chain Contract Library" description: "Contract references for Compose modules and facets—interfaces, storage layout, and upgrade wiring." sidebar_class_name: "hidden" --- diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index eb246476..40613226 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -161,6 +161,7 @@ const config = { /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ ({ image: 'img/socialcard-compose.png', + titleTemplate: '%s | Compose', colorMode: { defaultMode: 'light', disableSwitch: false, diff --git a/website/src/pages/index.js b/website/src/pages/index.js index a9a71566..637c6064 100644 --- a/website/src/pages/index.js +++ b/website/src/pages/index.js @@ -9,7 +9,7 @@ import CtaSection from '../components/home/CtaSection'; export default function Home() { return (
From 3ce1405748333c7a3b30025051bacad4d4abfc5d Mon Sep 17 00:00:00 2001 From: maxnorm Date: Fri, 5 Jun 2026 17:34:31 -0400 Subject: [PATCH 2/8] simplify robots.txt, inject canonical links --- website/docusaurus.config.js | 1 + website/plugins/canonical-inject.js | 75 +++++++++++++++++++++++++++++ website/static/robots.txt | 11 ----- 3 files changed, 76 insertions(+), 11 deletions(-) create mode 100644 website/plugins/canonical-inject.js diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 40613226..e1ef4390 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -330,6 +330,7 @@ const config = { }), plugins: [ path.join(__dirname, 'plugins', 'markdown-source-docs.js'), + path.join(__dirname, 'plugins', 'canonical-inject.js'), [ '@acid-info/docusaurus-og', { diff --git a/website/plugins/canonical-inject.js b/website/plugins/canonical-inject.js new file mode 100644 index 00000000..66962acb --- /dev/null +++ b/website/plugins/canonical-inject.js @@ -0,0 +1,75 @@ +/** + * Local plugin: injects into every HTML file after build. + * Guarantees the tag is in the initial server-rendered HTML — no JS required. + */ +import { createRequire } from 'module'; +import path from 'path'; +import { fileURLToPath } from 'url'; + +const __dirname = path.dirname(fileURLToPath(import.meta.url)); +const require = createRequire(import.meta.url); +const fs = require('fs-extra'); + +function findHtmlFiles(dir) { + const results = []; + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const fullPath = path.join(dir, entry.name); + if (entry.isDirectory()) { + results.push(...findHtmlFiles(fullPath)); + } else if (entry.name.endsWith('.html')) { + results.push(fullPath); + } + } + return results; +} + +/** + * Convert a file path relative to outDir into a URL path. + * e.g. "/docs/foundations/diamond-contracts/index.html" -> "/docs/foundations/diamond-contracts" + */ +function filePathToUrlPath(filePath, outDir) { + let rel = path.relative(outDir, filePath).split(path.sep).join('/'); + // /foo/index.html -> /foo + rel = rel.replace(/\/index\.html$/, ''); + // index.html -> / + if (rel === 'index') rel = ''; + return '/' + rel; +} + +export default function canonicalPlugin(context, options) { + const { url: siteUrl } = context.siteConfig; + const tag = ' into HTML files...'); + const htmlFiles = findHtmlFiles(outDir); + let count = 0; + + for (const filePath of htmlFiles) { + let html = fs.readFileSync(filePath, 'utf8'); + + // Skip if canonical already exists + if (html.includes(tag)) continue; + + const urlPath = filePathToUrlPath(filePath, outDir); + const canonical = `${siteUrl}${urlPath}`; + + // Inject right after or after the last in + const headIndex = html.indexOf(' of tag + const headClose = html.indexOf('>', headIndex); + const insertAt = headClose + 1; + + const canonicalTag = `\n `; + html = html.slice(0, insertAt) + canonicalTag + html.slice(insertAt); + + fs.writeFileSync(filePath, html, 'utf8'); + count++; + } + }, + }; +} diff --git a/website/static/robots.txt b/website/static/robots.txt index dd02d3d2..14e69940 100644 --- a/website/static/robots.txt +++ b/website/static/robots.txt @@ -1,25 +1,14 @@ # Robots.txt for Compose Documentation -# Allow all search engines to crawl the site User-agent: * Allow: / -# Disallow tag pages (low-value, duplicate content) Disallow: /tags/ - -# Disallow search pages (dynamic, no-index content) Disallow: /search - -# Disallow any admin or internal paths Disallow: /admin/ Disallow: /_next/ Disallow: /api/ -# Allow important content paths explicitly -Allow: /docs -Allow: /blog -Allow: / - # Sitemap location Sitemap: https://compose.diamonds/sitemap.xml From bd492fb506b44ade1e82fbd0a39c6a27fbbbd1ae Mon Sep 17 00:00:00 2001 From: maxnorm Date: Fri, 5 Jun 2026 17:53:24 -0400 Subject: [PATCH 3/8] add json-ld schemas --- website/docusaurus.config.js | 22 ++++++++ website/src/theme/DocItem/Layout/index.js | 2 + .../src/theme/DocItem/StructuredData/index.js | 50 +++++++++++++++++++ 3 files changed, 74 insertions(+) create mode 100644 website/src/theme/DocItem/StructuredData/index.js diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index e1ef4390..4b9ad8e9 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -107,6 +107,28 @@ const config = { logo: 'https://compose.diamonds/img/logo.svg', }), }, + { + tagName: 'script', + attributes: { + type: 'application/ld+json', + }, + innerHTML: JSON.stringify({ + '@context': 'https://schema.org/', + '@type': 'WebSite', + name: 'Compose', + url: 'https://compose.diamonds/', + about: "Modular Smart Contract Library for ERC-2535 / ERC-8153 diamond proxies", + author: "Perfect Abstractions & the Compose Community", + potentialAction: { + '@type': 'SearchAction', + target: { + '@type': 'EntryPoint', + urlTemplate: 'https://compose.diamonds/?q={search_term_string}', + }, + 'query-input': 'required name=search_term_string', + }, + }), + }, { tagName: "meta", attributes: { diff --git a/website/src/theme/DocItem/Layout/index.js b/website/src/theme/DocItem/Layout/index.js index 456528b3..3a1552f4 100644 --- a/website/src/theme/DocItem/Layout/index.js +++ b/website/src/theme/DocItem/Layout/index.js @@ -15,6 +15,7 @@ import DocItemContent from '@theme/DocItem/Content'; import DocBreadcrumbs from '@theme/DocBreadcrumbs'; import ContentVisibility from '@theme/ContentVisibility'; import DocPageAside from '@site/src/components/docs/DocPageAside'; +import DocItemStructuredData from '@theme/DocItem/StructuredData'; import styles from './styles.module.css'; @@ -49,6 +50,7 @@ export default function DocItemLayout({ children }) { return (
+
+ + + ); +} From af1bdb9d5cd91123496f9a7f63c4e8ba74586501 Mon Sep 17 00:00:00 2001 From: maxnorm Date: Fri, 5 Jun 2026 18:28:05 -0400 Subject: [PATCH 4/8] add specific sidebar label --- website/docs/contribution/cli/templates.mdx | 1 + website/docs/contribution/code-style-guide.mdx | 1 + website/docs/contribution/documentation/all-components.mdx | 1 + .../docs/contribution/documentation/system-design-guide.mdx | 1 + website/docs/contribution/how-to-contribute.mdx | 1 + website/docs/contribution/testing.mdx | 1 + website/docs/design/banned-solidity-features.mdx | 1 + website/docs/design/design-for-composition.mdx | 3 ++- website/docs/design/index.mdx | 1 + website/docs/design/maintain-compatibility.mdx | 3 ++- website/docs/design/repeat-yourself.mdx | 3 ++- website/docs/design/written-to-be-read.mdx | 3 ++- website/docs/foundations/composable-facets.mdx | 3 ++- website/docs/foundations/custom-facets.mdx | 3 ++- website/docs/foundations/diamond-contracts.mdx | 3 ++- website/docs/foundations/facets-and-modules.mdx | 3 ++- website/docs/foundations/index.mdx | 1 + website/docs/foundations/onchain-contract-library.mdx | 3 ++- website/docs/foundations/reusable-facet-logic.mdx | 3 ++- website/docs/foundations/solidity-modules.mdx | 3 ++- website/docs/getting-started/installation.md | 1 + website/docs/intro.mdx | 1 + website/docs/library/access/Owner/TwoSteps/index.mdx | 1 + website/docs/library/access/Owner/index.mdx | 1 + website/docs/library/access/index.mdx | 1 + website/docs/library/diamond/index.mdx | 1 + website/docs/library/index.mdx | 1 + 27 files changed, 38 insertions(+), 11 deletions(-) diff --git a/website/docs/contribution/cli/templates.mdx b/website/docs/contribution/cli/templates.mdx index 604915b0..987e2d4f 100644 --- a/website/docs/contribution/cli/templates.mdx +++ b/website/docs/contribution/cli/templates.mdx @@ -1,6 +1,7 @@ --- sidebar_position: 3 title: "CLI Project Templates" +sidebar_label: "Templates" description: How to add new project templates to the Compose CLI and keep the template registry in sync. --- diff --git a/website/docs/contribution/code-style-guide.mdx b/website/docs/contribution/code-style-guide.mdx index 9523eea3..cea9a060 100644 --- a/website/docs/contribution/code-style-guide.mdx +++ b/website/docs/contribution/code-style-guide.mdx @@ -1,6 +1,7 @@ --- sidebar_position: 3 title: "Code Style Guide — Solidity Conventions" +sidebar_label: "Code Style" description: Code style guidelines for developing Compose facets and modules --- diff --git a/website/docs/contribution/documentation/all-components.mdx b/website/docs/contribution/documentation/all-components.mdx index f4f21864..dd9235f8 100644 --- a/website/docs/contribution/documentation/all-components.mdx +++ b/website/docs/contribution/documentation/all-components.mdx @@ -1,6 +1,7 @@ --- sidebar_position: 2 title: All Components - Complete Reference +sidebar_label: "All Components" description: Complete reference of all documentation UI components—Badge, Callout, Accordion, APIReference, and more—with usage examples for Compose docs. draft: true --- diff --git a/website/docs/contribution/documentation/system-design-guide.mdx b/website/docs/contribution/documentation/system-design-guide.mdx index 4d3241e2..10cc6e73 100644 --- a/website/docs/contribution/documentation/system-design-guide.mdx +++ b/website/docs/contribution/documentation/system-design-guide.mdx @@ -1,6 +1,7 @@ --- sidebar_position: 1 title: Documentation Design Guide +sidebar_label: "Design Guide" description: Comprehensive guide for creating consistent, high-quality documentation draft: true --- diff --git a/website/docs/contribution/how-to-contribute.mdx b/website/docs/contribution/how-to-contribute.mdx index 2e3144cb..08b6a790 100644 --- a/website/docs/contribution/how-to-contribute.mdx +++ b/website/docs/contribution/how-to-contribute.mdx @@ -1,6 +1,7 @@ --- sidebar_position: 1 title: "How to Contribute to Compose" +sidebar_label: "How to Contribute" description: Learn how to contribute to Compose --- diff --git a/website/docs/contribution/testing.mdx b/website/docs/contribution/testing.mdx index d34881a6..75a523db 100644 --- a/website/docs/contribution/testing.mdx +++ b/website/docs/contribution/testing.mdx @@ -1,6 +1,7 @@ --- sidebar_position: 4 title: "Testing — Behavior-First with Foundry" +sidebar_label: "Testing" description: Compose tests are **behavior-first** and primarily written with Foundry fuzz tests. --- diff --git a/website/docs/design/banned-solidity-features.mdx b/website/docs/design/banned-solidity-features.mdx index 3188f15b..efa24ee9 100644 --- a/website/docs/design/banned-solidity-features.mdx +++ b/website/docs/design/banned-solidity-features.mdx @@ -1,6 +1,7 @@ --- sidebar_position: 4 title: "Banned Solidity Features" +sidebar_label: "Banned Features" description: Solidity language features that are banned from Compose facets and modules. --- diff --git a/website/docs/design/design-for-composition.mdx b/website/docs/design/design-for-composition.mdx index 310d192e..71f2dccd 100644 --- a/website/docs/design/design-for-composition.mdx +++ b/website/docs/design/design-for-composition.mdx @@ -1,6 +1,7 @@ --- -sidebar_position: 5 +sidebar_position: 3 title: "Design for Composition — Guidelines & Rules" +sidebar_label: "Composition" description: How to design Compose facets and modules for composition. --- diff --git a/website/docs/design/index.mdx b/website/docs/design/index.mdx index 0cfe0561..dc528d69 100644 --- a/website/docs/design/index.mdx +++ b/website/docs/design/index.mdx @@ -1,6 +1,7 @@ --- sidebar_position: 1 title: "Design Principles" +sidebar_label: "Overview" description: Overview for how Compose is designed sidebar_class_name: hidden --- diff --git a/website/docs/design/maintain-compatibility.mdx b/website/docs/design/maintain-compatibility.mdx index c3ceecff..8145dd78 100644 --- a/website/docs/design/maintain-compatibility.mdx +++ b/website/docs/design/maintain-compatibility.mdx @@ -1,6 +1,7 @@ --- -sidebar_position: 6 +sidebar_position: 5 title: "Maintain Compatibility — Standards & Interoperability" +sidebar_label: "Compatibility" description: Maintain compatibility with existing standards, libraries, and systems --- diff --git a/website/docs/design/repeat-yourself.mdx b/website/docs/design/repeat-yourself.mdx index 4f488168..559993c3 100644 --- a/website/docs/design/repeat-yourself.mdx +++ b/website/docs/design/repeat-yourself.mdx @@ -1,6 +1,7 @@ --- -sidebar_position: 3 +sidebar_position: 2 title: "Repeat Yourself — Intentional Code Duplication" +sidebar_label: "Repeat Yourself" description: Repeat yourself when it makes your code easier to read and understand. --- diff --git a/website/docs/design/written-to-be-read.mdx b/website/docs/design/written-to-be-read.mdx index 75964c52..298465c5 100644 --- a/website/docs/design/written-to-be-read.mdx +++ b/website/docs/design/written-to-be-read.mdx @@ -1,6 +1,7 @@ --- -sidebar_position: 2 +sidebar_position: 1 title: "Written to Be Read — Code Readability First" +sidebar_label: "Readability" description: Compose is written to be read by other developers. --- diff --git a/website/docs/foundations/composable-facets.mdx b/website/docs/foundations/composable-facets.mdx index c568bc58..14cccce4 100644 --- a/website/docs/foundations/composable-facets.mdx +++ b/website/docs/foundations/composable-facets.mdx @@ -1,6 +1,7 @@ --- -sidebar_position: 6 +sidebar_position: 5 title: "Composable Facets — Modular Building Blocks" +sidebar_label: "Composable Facets" description: Mix and match facets to build complex systems from simple, interoperable building blocks. --- diff --git a/website/docs/foundations/custom-facets.mdx b/website/docs/foundations/custom-facets.mdx index 502205e5..e22bc343 100644 --- a/website/docs/foundations/custom-facets.mdx +++ b/website/docs/foundations/custom-facets.mdx @@ -1,6 +1,7 @@ --- -sidebar_position: 8 +sidebar_position: 7 title: "Custom Facets — Build Your Own" +sidebar_label: "Custom Facets" description: "Build your own facets that work seamlessly with existing Compose Functionality." --- diff --git a/website/docs/foundations/diamond-contracts.mdx b/website/docs/foundations/diamond-contracts.mdx index c3e099e7..fa0e542f 100644 --- a/website/docs/foundations/diamond-contracts.mdx +++ b/website/docs/foundations/diamond-contracts.mdx @@ -1,6 +1,7 @@ --- -sidebar_position: 2 +sidebar_position: 1 title: "Diamond Contracts — Facets, Storage & Delegation" +sidebar_label: "Diamond Contracts" description: "Understand Diamonds from the ground up—facets, storage, delegation, and how Compose uses them." --- diff --git a/website/docs/foundations/facets-and-modules.mdx b/website/docs/foundations/facets-and-modules.mdx index f32f64e8..fa9e59de 100644 --- a/website/docs/foundations/facets-and-modules.mdx +++ b/website/docs/foundations/facets-and-modules.mdx @@ -1,6 +1,7 @@ --- -sidebar_position: 7 +sidebar_position: 6 title: "Facets and Modules — How They Work Together" +sidebar_label: "Facets & Modules" description: Learn how facets and modules work together through shared storage to build composable systems. --- diff --git a/website/docs/foundations/index.mdx b/website/docs/foundations/index.mdx index 3d170997..221d602d 100644 --- a/website/docs/foundations/index.mdx +++ b/website/docs/foundations/index.mdx @@ -1,5 +1,6 @@ --- title: "Foundations — Core Concepts" +sidebar_label: "Overview" description: Compose smart contracts are designed to be composable. sidebar_class_name: hidden --- diff --git a/website/docs/foundations/onchain-contract-library.mdx b/website/docs/foundations/onchain-contract-library.mdx index 4956fc05..5530b885 100644 --- a/website/docs/foundations/onchain-contract-library.mdx +++ b/website/docs/foundations/onchain-contract-library.mdx @@ -1,6 +1,7 @@ --- -sidebar_position: 4 +sidebar_position: 3 title: "On-chain Contract Library" +sidebar_label: "On-chain Library" description: Compose provides a set of reusable on-chain contracts that already exist on blockchains --- diff --git a/website/docs/foundations/reusable-facet-logic.mdx b/website/docs/foundations/reusable-facet-logic.mdx index 6c0231c3..8fb4734e 100644 --- a/website/docs/foundations/reusable-facet-logic.mdx +++ b/website/docs/foundations/reusable-facet-logic.mdx @@ -1,6 +1,7 @@ --- -sidebar_position: 5 +sidebar_position: 4 title: "Reusable Facet Logic — Deploy Once, Reuse Everywhere" +sidebar_label: "Reusable Logic" description: Deploy once, reuse everywhere. Compose facets are shared across thousands of projects. --- diff --git a/website/docs/foundations/solidity-modules.mdx b/website/docs/foundations/solidity-modules.mdx index 4124d47c..cb3e7b37 100644 --- a/website/docs/foundations/solidity-modules.mdx +++ b/website/docs/foundations/solidity-modules.mdx @@ -1,6 +1,7 @@ --- -sidebar_position: 3 +sidebar_position: 2 title: "Solidity Modules — Reusable Logic Outside Contracts" +sidebar_label: "Solidity Modules" description: What Solidity modules are, how they differ from contracts and libraries, and how Compose uses them for reusable facet logic and shared storage. --- diff --git a/website/docs/getting-started/installation.md b/website/docs/getting-started/installation.md index 6dd93fcc..c52f672b 100644 --- a/website/docs/getting-started/installation.md +++ b/website/docs/getting-started/installation.md @@ -1,6 +1,7 @@ --- sidebar_position: 1 title: "Installation" +sidebar_label: "Installation" description: "Get up and running with Compose in just a few minutes." --- diff --git a/website/docs/intro.mdx b/website/docs/intro.mdx index 3fdf785c..be8889e2 100644 --- a/website/docs/intro.mdx +++ b/website/docs/intro.mdx @@ -2,6 +2,7 @@ sidebar_position: 1 slug: / title: "Smart Contract Library for ERC-2535 / ERC-8153 Diamonds" +sidebar_label: "Introduction" description: Compose is a smart contract library for building smart contract systems using the ERC-2535 Diamond standard. --- diff --git a/website/docs/library/access/Owner/TwoSteps/index.mdx b/website/docs/library/access/Owner/TwoSteps/index.mdx index 78745ef6..cf6e3aaf 100644 --- a/website/docs/library/access/Owner/TwoSteps/index.mdx +++ b/website/docs/library/access/Owner/TwoSteps/index.mdx @@ -1,5 +1,6 @@ --- title: "Two Steps" +sidebar_label: "Two Steps" description: "Two Steps components for Compose diamonds." --- diff --git a/website/docs/library/access/Owner/index.mdx b/website/docs/library/access/Owner/index.mdx index 838542c3..b63ba2ec 100644 --- a/website/docs/library/access/Owner/index.mdx +++ b/website/docs/library/access/Owner/index.mdx @@ -1,5 +1,6 @@ --- title: "Owner" +sidebar_label: "Owner" description: "Single-owner access control pattern." --- diff --git a/website/docs/library/access/index.mdx b/website/docs/library/access/index.mdx index cb670a07..4208fc50 100644 --- a/website/docs/library/access/index.mdx +++ b/website/docs/library/access/index.mdx @@ -1,5 +1,6 @@ --- title: "Access Control — Diamond Permission Management" +sidebar_label: "Access Control" description: "Access control patterns for permission management in Compose diamonds." --- diff --git a/website/docs/library/diamond/index.mdx b/website/docs/library/diamond/index.mdx index 0e79cbc9..3d8a64e4 100644 --- a/website/docs/library/diamond/index.mdx +++ b/website/docs/library/diamond/index.mdx @@ -1,5 +1,6 @@ --- title: "Diamond Core — Proxy Functionality" +sidebar_label: "Diamond Core" description: "Core diamond proxy functionality for ERC-2535 diamonds." --- diff --git a/website/docs/library/index.mdx b/website/docs/library/index.mdx index 37feb0e1..cde0789a 100644 --- a/website/docs/library/index.mdx +++ b/website/docs/library/index.mdx @@ -1,5 +1,6 @@ --- title: "On-chain Contract Library" +sidebar_label: "Library" description: "Contract references for Compose modules and facets—interfaces, storage layout, and upgrade wiring." sidebar_class_name: "hidden" --- From e7b7582a987bd181483dce6bb7408fdb143d2aeb Mon Sep 17 00:00:00 2001 From: maxnorm Date: Fri, 5 Jun 2026 18:49:14 -0400 Subject: [PATCH 5/8] add proper h1 --- website/docs/contribution/code-style-guide.mdx | 2 ++ website/docs/contribution/how-to-contribute.mdx | 2 ++ website/docs/contribution/testing.mdx | 2 ++ website/docs/design/banned-solidity-features.mdx | 2 ++ website/docs/design/design-for-composition.mdx | 2 ++ website/docs/design/maintain-compatibility.mdx | 2 ++ website/docs/design/repeat-yourself.mdx | 1 + website/docs/design/written-to-be-read.mdx | 1 + website/docs/foundations/composable-facets.mdx | 2 ++ website/docs/foundations/custom-facets.mdx | 2 ++ website/docs/foundations/diamond-contracts.mdx | 2 ++ website/docs/foundations/facets-and-modules.mdx | 2 ++ website/docs/foundations/onchain-contract-library.mdx | 2 ++ website/docs/foundations/reusable-facet-logic.mdx | 2 ++ website/docs/foundations/solidity-modules.mdx | 1 + website/docs/intro.mdx | 1 + 16 files changed, 28 insertions(+) diff --git a/website/docs/contribution/code-style-guide.mdx b/website/docs/contribution/code-style-guide.mdx index cea9a060..b98322a8 100644 --- a/website/docs/contribution/code-style-guide.mdx +++ b/website/docs/contribution/code-style-guide.mdx @@ -5,6 +5,8 @@ sidebar_label: "Code Style" description: Code style guidelines for developing Compose facets and modules --- +# Code Style Guide + This section outlines the code style guidelines for developing new facets and Solidity modules in **Compose**. Follow [Compose's design principles](/docs/design) when contributing code. diff --git a/website/docs/contribution/how-to-contribute.mdx b/website/docs/contribution/how-to-contribute.mdx index 08b6a790..f7b15a93 100644 --- a/website/docs/contribution/how-to-contribute.mdx +++ b/website/docs/contribution/how-to-contribute.mdx @@ -5,6 +5,8 @@ sidebar_label: "How to Contribute" description: Learn how to contribute to Compose --- +# How to Contribute + Thank you for your interest in contributing to Compose! Compose is a community developed project. We welcome you and want your help. diff --git a/website/docs/contribution/testing.mdx b/website/docs/contribution/testing.mdx index 75a523db..6ba08ccb 100644 --- a/website/docs/contribution/testing.mdx +++ b/website/docs/contribution/testing.mdx @@ -5,6 +5,8 @@ sidebar_label: "Testing" description: Compose tests are **behavior-first** and primarily written with Foundry fuzz tests. --- +# Testing + Compose tests are **behavior-first** and primarily written with Foundry fuzz tests. ## Testing Philosophy diff --git a/website/docs/design/banned-solidity-features.mdx b/website/docs/design/banned-solidity-features.mdx index efa24ee9..9d661326 100644 --- a/website/docs/design/banned-solidity-features.mdx +++ b/website/docs/design/banned-solidity-features.mdx @@ -7,6 +7,8 @@ description: Solidity language features that are banned from Compose facets and import Callout from '@site/src/components/ui/Callout'; +# Banned Solidity Features + The following Solidity language features are **banned** from Compose facets and modules. Compose restricts certain Solidity features to keep facet and library code **simpler**, **more consistent**, and **easier to reason about**. diff --git a/website/docs/design/design-for-composition.mdx b/website/docs/design/design-for-composition.mdx index 71f2dccd..ed89c2fa 100644 --- a/website/docs/design/design-for-composition.mdx +++ b/website/docs/design/design-for-composition.mdx @@ -8,6 +8,8 @@ description: How to design Compose facets and modules for composition. import Callout from '@site/src/components/ui/Callout'; import ExpandableCode from '@site/src/components/code/ExpandableCode'; +# Design for Composition + Here are the guidelines and rules for creating composable facets. Compose replaces source-code inheritance with on-chain composition. Facets are the building blocks; diamonds wire them together. diff --git a/website/docs/design/maintain-compatibility.mdx b/website/docs/design/maintain-compatibility.mdx index 8145dd78..be3a4b14 100644 --- a/website/docs/design/maintain-compatibility.mdx +++ b/website/docs/design/maintain-compatibility.mdx @@ -5,6 +5,8 @@ sidebar_label: "Compatibility" description: Maintain compatibility with existing standards, libraries, and systems --- +# Maintain Compatibility + Build for interoperability. Before implementing a facet or feature, identify existing standards and expected behaviors, and ensure your implementation behaves the same where it matters. Code style can differ; externally observable behavior should not. Implementation checklist: diff --git a/website/docs/design/repeat-yourself.mdx b/website/docs/design/repeat-yourself.mdx index 559993c3..bd0de2aa 100644 --- a/website/docs/design/repeat-yourself.mdx +++ b/website/docs/design/repeat-yourself.mdx @@ -7,6 +7,7 @@ description: Repeat yourself when it makes your code easier to read and understa import Callout from '@site/src/components/ui/Callout'; +# Repeat Yourself The DRY principle — *Don't Repeat Yourself* — is a well-known rule in software development. We **intentionally** break that rule. diff --git a/website/docs/design/written-to-be-read.mdx b/website/docs/design/written-to-be-read.mdx index 298465c5..eebab6e3 100644 --- a/website/docs/design/written-to-be-read.mdx +++ b/website/docs/design/written-to-be-read.mdx @@ -5,6 +5,7 @@ sidebar_label: "Readability" description: Compose is written to be read by other developers. --- +# Written to Be Read The primary design principle of Compose is **the code should be easy to read and understand**. diff --git a/website/docs/foundations/composable-facets.mdx b/website/docs/foundations/composable-facets.mdx index 14cccce4..46c5a2eb 100644 --- a/website/docs/foundations/composable-facets.mdx +++ b/website/docs/foundations/composable-facets.mdx @@ -7,6 +7,8 @@ description: Mix and match facets to build complex systems from simple, interope import Callout from '@site/src/components/ui/Callout'; +# Composable Facets + The word **"composable"** means *able to be combined with other parts to form a whole*. In **Compose**, facets are designed to be **composable**. They're built to interoperate seamlessly with other facets inside the same diamond. diff --git a/website/docs/foundations/custom-facets.mdx b/website/docs/foundations/custom-facets.mdx index e22bc343..eb4b6b36 100644 --- a/website/docs/foundations/custom-facets.mdx +++ b/website/docs/foundations/custom-facets.mdx @@ -7,6 +7,8 @@ description: "Build your own facets that work seamlessly with existing Compose F import Callout from '@site/src/components/ui/Callout'; +# Custom Facets + Many projects need custom functionality beyond the standard facets. Compose is designed for this — you can build and integrate your own facets that work seamlessly alongside existing Compose facets. diff --git a/website/docs/foundations/diamond-contracts.mdx b/website/docs/foundations/diamond-contracts.mdx index fa0e542f..b9645bdd 100644 --- a/website/docs/foundations/diamond-contracts.mdx +++ b/website/docs/foundations/diamond-contracts.mdx @@ -8,6 +8,8 @@ description: "Understand Diamonds from the ground up—facets, storage, delegati import SvgThemeRenderer from '@site/src/components/theme/SvgThemeRenderer'; import Callout from '@site/src/components/ui/Callout'; +# Diamond Contracts + A **diamond contract** is a smart contract that is made up of multiple parts instead of one large block of code. The diamond exists at **one address** and holds **all of the contract's storage**, but it uses separate smart contracts called **facets** to provide its functionality. Users interact only with the **diamond**, but the diamond's features come from its **facets**. Each facet provides a small, focused set of functions, and the diamond uses those functions to perform its actions. diff --git a/website/docs/foundations/facets-and-modules.mdx b/website/docs/foundations/facets-and-modules.mdx index fa9e59de..ab6b6525 100644 --- a/website/docs/foundations/facets-and-modules.mdx +++ b/website/docs/foundations/facets-and-modules.mdx @@ -5,6 +5,8 @@ sidebar_label: "Facets & Modules" description: Learn how facets and modules work together through shared storage to build composable systems. --- +# Facets and Modules + Compose uses two complementary patterns for smart contract development: ### Facets (Complete Implementations) diff --git a/website/docs/foundations/onchain-contract-library.mdx b/website/docs/foundations/onchain-contract-library.mdx index 5530b885..c0e82682 100644 --- a/website/docs/foundations/onchain-contract-library.mdx +++ b/website/docs/foundations/onchain-contract-library.mdx @@ -8,6 +8,8 @@ description: Compose provides a set of reusable on-chain contracts that already import DocSubtitle from '@site/src/components/docs/DocSubtitle'; import Callout from '@site/src/components/ui/Callout'; +# On-chain Contract Library + **Compose takes a different approach.** diff --git a/website/docs/foundations/reusable-facet-logic.mdx b/website/docs/foundations/reusable-facet-logic.mdx index 8fb4734e..425ba2fc 100644 --- a/website/docs/foundations/reusable-facet-logic.mdx +++ b/website/docs/foundations/reusable-facet-logic.mdx @@ -8,6 +8,8 @@ description: Deploy once, reuse everywhere. Compose facets are shared across tho import DiamondFacetsSVG from '@site/static/img/svg/compose_diamond_facets.svg' import Callout from '@site/src/components/ui/Callout'; +# Reusable Facet Logic + You might be wondering: **How can I create a new project without deploying new smart contracts?** The answer lies in Compose's smart contract architecture, which is based on [diamond contracts](/docs/foundations/diamond-contracts). diff --git a/website/docs/foundations/solidity-modules.mdx b/website/docs/foundations/solidity-modules.mdx index cb3e7b37..4182f29b 100644 --- a/website/docs/foundations/solidity-modules.mdx +++ b/website/docs/foundations/solidity-modules.mdx @@ -7,6 +7,7 @@ description: What Solidity modules are, how they differ from contracts and libra import ExpandableCode from '@site/src/components/code/ExpandableCode'; +# Solidity Modules Solidity **modules** are Solidity files whose top-level code lives *outside* of contracts and Solidity libraries. They contain reusable logic that gets pulled into other contracts at compile time. diff --git a/website/docs/intro.mdx b/website/docs/intro.mdx index be8889e2..c7d42e25 100644 --- a/website/docs/intro.mdx +++ b/website/docs/intro.mdx @@ -11,6 +11,7 @@ import DocCard, { DocCardGrid } from '@site/src/components/docs/DocCard'; import Callout from '@site/src/components/ui/Callout'; import FeatureGrid, { FeatureGridItem } from '@site/src/components/features/FeatureGrid'; +# Introduction to Compose **Compose** is a smart contract library that helps developers build smart contract systems using the [ERC-2535 Diamond](https://eips.ethereum.org/EIPS/eip-2535) standard. It's designed from the ground up for **code clarity**, **reusability**, and **on-chain composability**. From b073265877646f8091ac4c057f6911b68091e1e1 Mon Sep 17 00:00:00 2001 From: maxnorm Date: Fri, 5 Jun 2026 18:58:38 -0400 Subject: [PATCH 6/8] update last headings --- website/docs/foundations/index.mdx | 2 ++ website/docs/library/index.mdx | 2 ++ 2 files changed, 4 insertions(+) diff --git a/website/docs/foundations/index.mdx b/website/docs/foundations/index.mdx index 221d602d..ba135285 100644 --- a/website/docs/foundations/index.mdx +++ b/website/docs/foundations/index.mdx @@ -11,6 +11,8 @@ import Icon from '@site/src/components/ui/Icon'; import CalloutBox from '@site/src/components/ui/CalloutBox'; import Callout from '@site/src/components/ui/Callout'; +# Foundations: Core Concepts of Compose + Compose is a new approach to smart contract development that changes how developers build and deploy smart contract systems. This section introduces the core concepts that make Compose unique. diff --git a/website/docs/library/index.mdx b/website/docs/library/index.mdx index cde0789a..f33d319a 100644 --- a/website/docs/library/index.mdx +++ b/website/docs/library/index.mdx @@ -10,6 +10,8 @@ import DocSubtitle from '@site/src/components/docs/DocSubtitle'; import Icon from '@site/src/components/ui/Icon'; import Callout from '@site/src/components/ui/Callout'; +# Compose Smart Contracts Library + Contract-level docs for each **Compose** module and facet. What to call on-chain, how state is organized, and how upgrades work. From 854b8df3aa9f7b023a1f7820a0c7247235ef3b82 Mon Sep 17 00:00:00 2001 From: maxnorm Date: Fri, 5 Jun 2026 19:03:13 -0400 Subject: [PATCH 7/8] fix remaining --- website/docs/library/access/index.mdx | 4 +++- website/docs/library/diamond/index.mdx | 2 ++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/website/docs/library/access/index.mdx b/website/docs/library/access/index.mdx index 4208fc50..fd76a38f 100644 --- a/website/docs/library/access/index.mdx +++ b/website/docs/library/access/index.mdx @@ -8,8 +8,10 @@ import DocCard, { DocCardGrid } from '@site/src/components/docs/DocCard'; import DocSubtitle from '@site/src/components/docs/DocSubtitle'; import Icon from '@site/src/components/ui/Icon'; +# Diamond Permission Management + - Access control for Compose diamonds. + Manage who can access your diamond using Ownership or Role-Based Access Control diff --git a/website/docs/library/diamond/index.mdx b/website/docs/library/diamond/index.mdx index 3d8a64e4..1d9d6d5c 100644 --- a/website/docs/library/diamond/index.mdx +++ b/website/docs/library/diamond/index.mdx @@ -8,6 +8,8 @@ import DocCard, { DocCardGrid } from '@site/src/components/docs/DocCard'; import DocSubtitle from '@site/src/components/docs/DocSubtitle'; import Icon from '@site/src/components/ui/Icon'; +#Diamond Core: Proxy Functionality + Core diamond proxy functionality for ERC-8153 diamonds. From ec5dd137ba35ed42f9abf0bd9a2bc1a723fcd41a Mon Sep 17 00:00:00 2001 From: maxnorm Date: Fri, 5 Jun 2026 19:08:23 -0400 Subject: [PATCH 8/8] fix typo --- website/docs/library/diamond/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/library/diamond/index.mdx b/website/docs/library/diamond/index.mdx index 1d9d6d5c..2268e125 100644 --- a/website/docs/library/diamond/index.mdx +++ b/website/docs/library/diamond/index.mdx @@ -8,7 +8,7 @@ import DocCard, { DocCardGrid } from '@site/src/components/docs/DocCard'; import DocSubtitle from '@site/src/components/docs/DocSubtitle'; import Icon from '@site/src/components/ui/Icon'; -#Diamond Core: Proxy Functionality +# Diamond Core: Proxy Functionality Core diamond proxy functionality for ERC-8153 diamonds.