From 6b65928b82bad973860bd53a02c95a891f8df7f7 Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Fri, 12 Dec 2025 13:32:55 +0530 Subject: [PATCH 1/2] feat: Implement Docusaurus versioning with new management scripts, guides, and sidebar styling. --- VERSIONING.md | 46 ++ docusaurus.config.ts | 39 +- package.json | 9 +- scripts/release-version.js | 47 ++ scripts/remove-version.js | 44 ++ scripts/reset-versions.js | 50 ++ src/theme/DocSidebar/index.tsx | 130 ++++-- src/theme/DocSidebar/styles.module.css | 47 ++ temp/docusaurus-versioning-guide.md | 606 +++++++++++++++++++++++++ 9 files changed, 960 insertions(+), 58 deletions(-) create mode 100644 VERSIONING.md create mode 100644 scripts/release-version.js create mode 100644 scripts/remove-version.js create mode 100644 scripts/reset-versions.js create mode 100644 src/theme/DocSidebar/styles.module.css create mode 100644 temp/docusaurus-versioning-guide.md diff --git a/VERSIONING.md b/VERSIONING.md new file mode 100644 index 0000000..ffc641c --- /dev/null +++ b/VERSIONING.md @@ -0,0 +1,46 @@ +# Versioning Guide + +This project uses Docusaurus versioning to manage documentation for different releases of the Yellow Network protocol and SDK. + +## Structure + +- **`docs/`**: functionality for the **upcoming/current** development version (labeled as "Next" or derived from `package.json`). +- **`versioned_docs/version-0.5.x/`**: Frozen documentation for the `0.5.x` stable release. + +## Workflows + +### 1. Releasing a New Version + +When you are ready to release the current work, this process involves **freezing** the current version (e.g., `0.6.x`) and **creating** the next development version (e.g., `0.7.x`). + +```bash +npm run version:release 0.6.x 0.7.x +``` + +This single command will: +1. Snapshot `docs/` to `versioned_docs/version-0.6.x`. +2. Update `package.json` version to `0.7.x` (which updates the "Next" dropdown label). + +### 2. Updating an Old Version + +To fix a typo or add a note to an old version (e.g., `0.5.x`): +- Edit the files in `versioned_docs/version-0.5.x/`. +- **Do not** edit files in `docs/` for old versions; `docs/` is always the *future* version. + +### 3. Removing an Old Version + +To remove an old version that is no longer supported (e.g., `0.5.x`): + +```bash +npm run version:remove 0.5.x +``` +This performs a safe, complete deletion of the version folder and config entry. + +### 4. Resetting to Single Version + +To delete ALL history and return to a single-version project (e.g., just `0.5.x`): + +```bash +npm run version:reset 0.5.x +``` +**Warning**: This deletes all `versioned_docs` folders. You will be left with only the current content in `docs/`, labeled as `0.5.x`. diff --git a/docusaurus.config.ts b/docusaurus.config.ts index c494f5e..f8f65d2 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -1,5 +1,5 @@ -import {themes as prismThemes} from 'prism-react-renderer'; -import type {Config} from '@docusaurus/types'; +import { themes as prismThemes } from 'prism-react-renderer'; +import type { Config } from '@docusaurus/types'; import type * as Preset from '@docusaurus/preset-classic'; // This runs in Node.js - Don't use client-side code here (browser APIs, JSX...) @@ -12,6 +12,10 @@ const config: Config = { tagline: 'Decentralized clearing and settlement network.\nDevelop Yellow Apps with instant finality.', favicon: 'img/favicon.ico', + customFields: { + packageVersion: require('./package.json').version, + }, + // Future flags, see https://docusaurus.io/docs/api/docusaurus-config#future future: { v4: true, // Improve compatibility with the upcoming Docusaurus v4 @@ -64,6 +68,19 @@ const config: Config = { sidebarCollapsed: false, sidebarCollapsible: false, breadcrumbs: true, + // includeCurrentVersion: true, + // lastVersion: '0.5.x', + // versions: { + // current: { + // label: require('./package.json').version, + // path: 'next', + // banner: 'unreleased', + // }, + // '0.5.x': { + // label: 'v0.5.x', + // path: '', + // }, + // }, }, blog: false, theme: { @@ -207,19 +224,19 @@ const config: Config = { defaultLanguage: 'javascript', magicComments: [ { - className: 'git-diff-remove', - line: 'remove-next-line', - block: { start: 'remove-start', end: 'remove-end' }, + className: 'git-diff-remove', + line: 'remove-next-line', + block: { start: 'remove-start', end: 'remove-end' }, }, { - className: 'git-diff-add', - line: 'add-next-line', - block: { start: 'add-start', end: 'add-end' }, + className: 'git-diff-add', + line: 'add-next-line', + block: { start: 'add-start', end: 'add-end' }, }, { - className: 'theme-code-block-highlighted-line', - line: 'highlight-next-line', - block: { start: 'highlight-start', end: 'highlight-end' }, + className: 'theme-code-block-highlighted-line', + line: 'highlight-next-line', + block: { start: 'highlight-start', end: 'highlight-end' }, }, ], }, diff --git a/package.json b/package.json index b7bf1f7..a5aa28b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "docs", - "version": "0.0.0", + "version": "0.5.x", "private": true, "scripts": { "docusaurus": "docusaurus", @@ -12,7 +12,10 @@ "serve": "docusaurus serve", "write-translations": "docusaurus write-translations", "write-heading-ids": "docusaurus write-heading-ids", - "typecheck": "tsc" + "typecheck": "tsc", + "version:remove": "node scripts/remove-version.js", + "version:reset": "node scripts/reset-versions.js", + "version:release": "node scripts/release-version.js" }, "dependencies": { "@docusaurus/core": "3.9.2", @@ -53,4 +56,4 @@ "engines": { "node": ">=18.0" } -} +} \ No newline at end of file diff --git a/scripts/release-version.js b/scripts/release-version.js new file mode 100644 index 0000000..be37515 --- /dev/null +++ b/scripts/release-version.js @@ -0,0 +1,47 @@ +const { execSync } = require('child_process'); +const fs = require('fs'); +const path = require('path'); + +const versionToFreeze = process.argv[2]; +const nextDevVersion = process.argv[3]; + +if (!versionToFreeze || !nextDevVersion) { + console.error('Usage: npm run version:release '); + console.error('Example: npm run version:release 0.5.x 0.6.x'); + process.exit(1); +} + +const rootDir = path.resolve(__dirname, '..'); +const packageJsonPath = path.join(rootDir, 'package.json'); +const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')); + +// Validation: Ensure the current project version matches the version being frozen. +// This prevents mistakes like being on 0.5.x but trying to freeze 0.6.x (skipping a version). +if (pkg.version !== versionToFreeze) { + console.error(`Error: Version mismatch.`); + console.error(`You are trying to freeze/release "${versionToFreeze}", but the current project version (in package.json) is "${pkg.version}".`); + console.error(`Please update package.json to "${versionToFreeze}" first, or check your release arguments.`); + process.exit(1); +} + +try { + // 1. Snapshot the current docs as the frozen version + console.log(`Freezing current docs as ${versionToFreeze}...`); + execSync(`npm run docusaurus docs:version ${versionToFreeze}`, { stdio: 'inherit' }); + + // 2. Bump package.json to the new dev version + console.log(`Creating next version ${nextDevVersion} (updating package.json)...`); + + // Update the version in the already loaded pkg object + pkg.version = nextDevVersion; + fs.writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2)); + + console.log('---------------------------------------------------'); + console.log(`Release Complete!`); + console.log(`- Frozen Version: ${versionToFreeze} (saved in versioned_docs/)`); + console.log(`- Created Next Version: ${nextDevVersion} (active in docs/)`); + +} catch (error) { + console.error('Release failed:', error.message); + process.exit(1); +} diff --git a/scripts/remove-version.js b/scripts/remove-version.js new file mode 100644 index 0000000..271ea62 --- /dev/null +++ b/scripts/remove-version.js @@ -0,0 +1,44 @@ +const fs = require('fs'); +const path = require('path'); + +const version = process.argv[2]; + +if (!version) { + console.error('Please provide a version to remove. Usage: npm run version:remove '); + process.exit(1); +} + +const rootDir = path.resolve(__dirname, '..'); +const versionsJsonPath = path.join(rootDir, 'versions.json'); +const versionedDocsPath = path.join(rootDir, 'versioned_docs', `version-${version}`); +const versionedSidebarsPath = path.join(rootDir, 'versioned_sidebars', `version-${version}-sidebars.json`); + +console.log(`Removing version ${version}...`); + +// 1. updates versions.json +if (fs.existsSync(versionsJsonPath)) { + const versions = JSON.parse(fs.readFileSync(versionsJsonPath, 'utf8')); + const newVersions = versions.filter(v => v !== version); + fs.writeFileSync(versionsJsonPath, JSON.stringify(newVersions, null, 2)); + console.log(`Updated versions.json`); +} else { + console.warn(`versions.json not found at ${versionsJsonPath}`); +} + +// 2. Removes versioned_docs/version- +if (fs.existsSync(versionedDocsPath)) { + fs.rmSync(versionedDocsPath, { recursive: true, force: true }); + console.log(`Removed ${versionedDocsPath}`); +} else { + console.warn(`Versioned docs not found at ${versionedDocsPath}`); +} + +// 3. Removes versioned_sidebars/version--sidebars.json +if (fs.existsSync(versionedSidebarsPath)) { + fs.rmSync(versionedSidebarsPath); + console.log(`Removed ${versionedSidebarsPath}`); +} else { + console.warn(`Versioned sidebar not found at ${versionedSidebarsPath}`); +} + +console.log(`Successfully removed version ${version}.`); diff --git a/scripts/reset-versions.js b/scripts/reset-versions.js new file mode 100644 index 0000000..0e21678 --- /dev/null +++ b/scripts/reset-versions.js @@ -0,0 +1,50 @@ +const fs = require('fs'); +const path = require('path'); + +const targetVersion = process.argv[2]; + +if (!targetVersion) { + console.error('Usage: npm run version:reset '); + console.error('Example: npm run version:reset 0.5.x'); + process.exit(1); +} + +const rootDir = path.resolve(__dirname, '..'); +const versionsJsonPath = path.join(rootDir, 'versions.json'); +const versionedDocsPath = path.join(rootDir, 'versioned_docs'); +const versionedSidebarsPath = path.join(rootDir, 'versioned_sidebars'); +const packageJsonPath = path.join(rootDir, 'package.json'); + +console.log(`WARNING: This will delete ALL historical versions and reset the project to single version '${targetVersion}'.`); + +// 1. Delete versioned folders +if (fs.existsSync(versionedDocsPath)) { + fs.rmSync(versionedDocsPath, { recursive: true, force: true }); + console.log('Removed versioned_docs/'); +} + +if (fs.existsSync(versionedSidebarsPath)) { + fs.rmSync(versionedSidebarsPath, { recursive: true, force: true }); + console.log('Removed versioned_sidebars/'); +} + +// 2. Delete versions.json +if (fs.existsSync(versionsJsonPath)) { + fs.rmSync(versionsJsonPath); + console.log('Removed versions.json'); +} + +// 3. Update package.json version +if (fs.existsSync(packageJsonPath)) { + const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')); + pkg.version = targetVersion; + fs.writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2)); + console.log(`Updated package.json version to ${targetVersion}`); +} + +console.log('---------------------------------------------------'); +console.log(`Reset Complete. The project is now single-version: ${targetVersion}`); +console.log('The "Next" version in the dropdown will now show this version.'); +console.log(''); +console.log('IMPORTANT: You must manually update docusaurus.config.ts to disable default versioning'); +console.log('configuration (comment out "lastVersion", "versions", etc.) until you serve a new version.'); diff --git a/src/theme/DocSidebar/index.tsx b/src/theme/DocSidebar/index.tsx index 8145c24..1caeed6 100644 --- a/src/theme/DocSidebar/index.tsx +++ b/src/theme/DocSidebar/index.tsx @@ -1,49 +1,91 @@ -import React, {useMemo} from 'react'; -import {useLocation} from '@docusaurus/router'; -import type {Props} from '@theme/DocSidebar'; -import DocSidebar from '@theme-original/DocSidebar'; +import React, { type ReactNode } from 'react'; +import OriginalSidebar from '@theme-original/DocSidebar'; +import { useVersions, useActiveVersion } from '@docusaurus/plugin-content-docs/client'; +import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; +// @ts-ignore - CSS modules are not typed by default in docusaurus setup without extra config +import styles from './styles.module.css'; +import type { PropSidebar } from '@docusaurus/plugin-content-docs'; -function CustomDocSidebar(props: Props): JSX.Element { - const location = useLocation(); +type Props = { + path: string; + sidebar: PropSidebar; + onCollapse: () => void; + isHidden: boolean; + [key: string]: any; +}; + +function VersionSwitcher() { + const { siteConfig } = useDocusaurusContext(); + const versions = useVersions(); + const activeVersion = useActiveVersion(); + const currentVersionLabel = (siteConfig.customFields?.packageVersion as string) || 'Next'; - const filteredSidebar = useMemo(() => { - if (!props.sidebar) return null; - - // Determine current section from pathname - const pathSegments = location.pathname.split('/').filter(Boolean); - const currentSection = pathSegments[1]; // docs/[section]/... - - if (!currentSection || currentSection === 'docs') { - return props.sidebar; - } - - // Filter sidebar items to show only current section - const filteredItems = props.sidebar.filter((item) => { - if (item.type === 'category') { - // Check if category belongs to current section by examining the category's items - return item.items && item.items.some((subItem: any) => { - const subItemPath = subItem.href || subItem.id || ''; - return subItemPath.includes(currentSection); - }); - } - - if (item.type === 'doc') { - const itemPath = (item as any).href || (item as any).id || ''; - return itemPath.includes(currentSection); - } - - if (item.type === 'link') { - const itemPath = (item as any).href || ''; - return itemPath.includes(currentSection); - } - - return false; - }); - - return filteredItems; - }, [props.sidebar, location.pathname]); + return ( +
+ + + + + + +
+ ); } -export default CustomDocSidebar; \ No newline at end of file +export default function DocSidebarWrapper(props: Props): ReactNode { + return ( + <> + + + + ); +} \ No newline at end of file diff --git a/src/theme/DocSidebar/styles.module.css b/src/theme/DocSidebar/styles.module.css new file mode 100644 index 0000000..642a884 --- /dev/null +++ b/src/theme/DocSidebar/styles.module.css @@ -0,0 +1,47 @@ +.versionSwitcher { + display: flex; + align-items: center; + gap: 8px; + padding: 12px 16px; + border-bottom: 1px solid var(--ifm-color-emphasis-200); + margin-bottom: 8px; + /* Fix for overlapping with fixed Navbar */ + margin-top: calc(var(--ifm-navbar-height) + 1rem); + background-color: var(--ifm-background-surface-color); + z-index: 100; + position: relative; +} + +.githubLink { + display: flex; + align-items: center; + color: var(--ifm-color-emphasis-700); + transition: color 0.2s; +} + +.githubLink:hover { + color: var(--ifm-color-primary); +} + +.versionSelect { + background: transparent; + border: none; + font-size: 14px; + font-weight: 500; + cursor: pointer; + padding: 4px 8px; + color: var(--ifm-font-color-base); + /* appearance: none; Was hiding the arrow. Removing it to show default browser arrow for now. */ +} + +/* Custom dropdown arrow styling to match wireframe "v0.53 ▼" */ +.versionDropdown { + position: relative; + display: inline-flex; + align-items: center; + cursor: pointer; +} + +.versionSelect:focus { + outline: none; +} \ No newline at end of file diff --git a/temp/docusaurus-versioning-guide.md b/temp/docusaurus-versioning-guide.md new file mode 100644 index 0000000..a184a11 --- /dev/null +++ b/temp/docusaurus-versioning-guide.md @@ -0,0 +1,606 @@ +# Docusaurus Version Switcher Implementation Guide +## Comprehensive Research for Yellow Network Documentation + +--- + +## Table of Contents +1. [Executive Summary](#executive-summary) +2. [Industry Standard Approaches](#industry-standard-approaches) +3. [Folder Structure for Versioning](#folder-structure-for-versioning) +4. [Implementation Steps](#implementation-steps) +5. [Configuration Examples](#configuration-examples) +6. [Matching Your Figma Wireframe](#matching-your-figma-wireframe) +7. [Recommended Approach for Yellow Network](#recommended-approach) +8. [Migration Strategy: 0.5.0 → 0.6.0](#migration-strategy) + +--- + +## Executive Summary + +Based on my research, Docusaurus provides built-in versioning capabilities that create a version dropdown in the navbar. The industry standard approach involves: + +1. **`versions.json`** file - Lists all available versions +2. **`versioned_docs/`** folder - Contains frozen documentation for each version +3. **`versioned_sidebars/`** folder - Contains sidebar configs per version +4. **`docs/`** folder - Always contains the "current" (next/development) version + +For your Yellow Network docs currently at v0.5.0, you'll want to set up versioning that allows users to switch between stable releases (like the wireframe shows with "v0.53"). + +--- + +## Industry Standard Approaches + +### Approach 1: Standard Docusaurus Versioning (Recommended for most cases) + +This is used by Facebook, Docusaurus itself, Jest, and many major projects. + +**How it works:** +- `docs/` folder = "current" version (labeled "Next" by default) +- When you release, run `npm run docusaurus docs:version X.X.X` +- Creates `versioned_docs/version-X.X.X/` with a copy of all docs +- Creates `versioned_sidebars/version-X.X.X-sidebars.json` +- Updates `versions.json` + +**Pros:** +- Simple to implement +- Built-in CLI commands +- Automatic version dropdown +- Page-aware version switching (stays on same page when switching versions) + +**Cons:** +- Duplicates files (can bloat repo for large docs) +- Build times increase with each version + +### Approach 2: Git Branch-Based Versioning (Used by Spectro Cloud) + +**How it works:** +- Each version lives in a separate git branch +- CI/CD builds and deploys each branch separately +- Custom version switcher redirects between deployed sites + +**Pros:** +- No file duplication in repo +- Cleaner git history +- Smaller repo size + +**Cons:** +- More complex CI/CD setup +- Harder to maintain consistency across versions +- Requires custom version switcher implementation + +### Approach 3: Hybrid - Version Labels Without Duplication (Used by Consensys) + +**How it works:** +- Single `docs/` folder for the "current" stable version +- Configure `lastVersion: 'current'` to avoid "Next" label +- Version label configured in `docusaurus.config.js` + +**Pros:** +- Simpler structure +- No file duplication +- Good for projects where older versions aren't maintained + +**Cons:** +- Only practical if you don't need to maintain multiple versions simultaneously + +--- + +## Folder Structure for Versioning + +### Standard Versioned Site Structure + +``` +yellow-docs/ +├── docs/ # Current (development/next) version +│ ├── learn/ +│ │ └── introduction.md +│ ├── build/ +│ │ └── getting-started.md +│ ├── manuals/ +│ │ └── protocol-guide.md +│ ├── tutorials/ +│ │ └── quickstart.md +│ └── api-reference/ +│ └── nitrolite-api.md +│ +├── versioned_docs/ # Frozen versions +│ ├── version-0.5.0/ +│ │ ├── learn/ +│ │ ├── build/ +│ │ ├── manuals/ +│ │ ├── tutorials/ +│ │ └── api-reference/ +│ │ +│ └── version-0.4.0/ # (if maintaining older versions) +│ ├── learn/ +│ └── ... +│ +├── versioned_sidebars/ # Sidebar configs per version +│ ├── version-0.5.0-sidebars.json +│ └── version-0.4.0-sidebars.json +│ +├── versions.json # List of versions ["0.5.0", "0.4.0"] +├── sidebars.js # Sidebar for current version +├── docusaurus.config.js # Main configuration +└── package.json +``` + +### versions.json Format + +```json +[ + "0.5.0", + "0.4.0" +] +``` + +Note: Versions are ordered from newest to oldest. The first version is considered the "latest" stable version. + +--- + +## Implementation Steps + +### Step 1: Add Version Dropdown to Navbar + +In `docusaurus.config.js`, add the `docsVersionDropdown` item to your navbar: + +```javascript +module.exports = { + themeConfig: { + navbar: { + // Your existing logo config + logo: { + alt: 'Yellow Network', + src: 'img/yellow-logo.svg', + }, + items: [ + // Existing items... + { + type: 'docsVersionDropdown', + position: 'left', // Position as shown in your Figma (top-left under logo) + dropdownActiveClassDisabled: true, + // Optional: Add "All versions" link + dropdownItemsAfter: [ + { + to: '/versions', + label: 'All versions', + }, + ], + }, + // Other navbar items... + ], + }, + }, +}; +``` + +### Step 2: Configure Docs Plugin with Versioning + +```javascript +module.exports = { + presets: [ + [ + '@docusaurus/preset-classic', + { + docs: { + sidebarPath: require.resolve('./sidebars.js'), + // Enable editing + editUrl: 'https://github.com/layer-3/docs/tree/master/', + + // Versioning configuration + lastVersion: '0.5.0', // This will be the default/latest version + + // Optional: Don't show "current" (development) version publicly + includeCurrentVersion: true, // Set to false to hide development docs + + versions: { + current: { + label: '0.6.0-dev', // Label for unreleased/development version + path: 'next', // URL path: /docs/next/ + banner: 'unreleased', // Show "unreleased" banner + }, + '0.5.0': { + label: 'v0.5.0', // Displayed in dropdown + path: '', // Default path: /docs/ + banner: 'none', // No banner for stable + }, + // Add more versions as needed + }, + }, + }, + ], + ], +}; +``` + +### Step 3: Create Your First Version + +When you're ready to release v0.5.0: + +```bash +# This creates versioned_docs/version-0.5.0/ and updates versions.json +npm run docusaurus docs:version 0.5.0 +``` + +### Step 4: Prepare for Next Version (0.6.0) + +After running the version command: +- `docs/` folder now represents v0.6.0 (development) +- `versioned_docs/version-0.5.0/` contains the frozen v0.5.0 docs +- Continue working on `docs/` for v0.6.0 features + +--- + +## Configuration Examples + +### Complete docusaurus.config.js Example + +```javascript +const config = { + title: 'Yellow Network', + tagline: 'Decentralized Clearing Network', + url: 'https://docs.yellow.org', + baseUrl: '/', + + presets: [ + [ + '@docusaurus/preset-classic', + { + docs: { + sidebarPath: require.resolve('./sidebars.js'), + editUrl: 'https://github.com/layer-3/docs/tree/master/', + routeBasePath: '/', // Docs at root URL + + // Versioning + lastVersion: '0.5.0', + includeCurrentVersion: true, + onlyIncludeVersions: ['current', '0.5.0'], // Limit versions for faster builds + + versions: { + current: { + label: 'v0.6.0 (dev)', + path: 'next', + banner: 'unreleased', + badge: true, + }, + '0.5.0': { + label: 'v0.5.0', + path: '', + banner: 'none', + badge: false, + }, + }, + }, + theme: { + customCss: require.resolve('./src/css/custom.css'), + }, + }, + ], + ], + + themeConfig: { + navbar: { + logo: { + alt: 'Yellow Network', + src: 'img/yellow-logo.svg', + }, + items: [ + // Version dropdown - matches your Figma wireframe placement + { + type: 'docsVersionDropdown', + position: 'left', + dropdownActiveClassDisabled: true, + }, + // Main navigation items + { + type: 'docSidebar', + sidebarId: 'learnSidebar', + position: 'left', + label: 'Learn', + }, + { + type: 'docSidebar', + sidebarId: 'buildSidebar', + position: 'left', + label: 'Build', + }, + { + type: 'docSidebar', + sidebarId: 'manualsSidebar', + position: 'left', + label: 'Manuals', + }, + { + type: 'docSidebar', + sidebarId: 'tutorialsSidebar', + position: 'left', + label: 'Tutorials', + }, + { + type: 'docSidebar', + sidebarId: 'apiSidebar', + position: 'left', + label: 'API Reference', + }, + // GitHub link + { + href: 'https://github.com/layer-3/docs', + position: 'right', + className: 'header-github-link', + 'aria-label': 'GitHub repository', + }, + ], + }, + + // Optional: Version announcement bar + announcementBar: { + id: 'version_announcement', + content: '📢 v0.5.0 is now available! See what\'s new', + backgroundColor: '#FFEC00', // Yellow Network brand color + textColor: '#000', + isCloseable: true, + }, + }, +}; + +module.exports = config; +``` + +--- + +## Matching Your Figma Wireframe + +Based on the wireframe you provided, here's how to achieve the exact look: + +### Sidebar Layout (Left Panel) +``` +┌─────────────────────────────┐ +│ yellow. │ ← Logo +├─────────────────────────────┤ +│ 🐙 v0.53 ▼ │ ← GitHub icon + Version dropdown +├─────────────────────────────┤ +│ Learn │ +│ Build │ +│ Manuals │ +│ Tutorials │ +│ API Reference │ +│ Legacy │ +└─────────────────────────────┘ +``` + +### Custom Sidebar Component for Version Switcher + +To get the exact layout from your Figma (GitHub icon + version dropdown in sidebar), create a custom sidebar component: + +```jsx +// src/theme/DocSidebar/index.js (swizzle the sidebar) +import React from 'react'; +import OriginalSidebar from '@theme-original/DocSidebar'; +import { + useVersions, + useActiveVersion, +} from '@docusaurus/plugin-content-docs/client'; +import styles from './styles.module.css'; + +function VersionSwitcher() { + const versions = useVersions(); + const activeVersion = useActiveVersion(); + + return ( +
+ + + + + + +
+ ); +} + +export default function DocSidebarWrapper(props) { + return ( + <> + + + + ); +} +``` + +### Custom CSS for Sidebar Version Switcher + +```css +/* src/theme/DocSidebar/styles.module.css */ + +.versionSwitcher { + display: flex; + align-items: center; + gap: 8px; + padding: 12px 16px; + border-bottom: 1px solid var(--ifm-color-emphasis-200); + margin-bottom: 8px; +} + +.githubLink { + display: flex; + align-items: center; + color: var(--ifm-color-emphasis-700); + transition: color 0.2s; +} + +.githubLink:hover { + color: var(--ifm-color-primary); +} + +.versionSelect { + background: var(--ifm-background-surface-color); + border: 1px solid var(--ifm-color-emphasis-300); + border-radius: 4px; + font-size: 14px; + font-weight: 500; + cursor: pointer; + padding: 6px 12px; + color: var(--ifm-font-color-base); +} + +.versionSelect:hover { + border-color: var(--ifm-color-primary); +} + +.versionSelect:focus { + outline: none; + border-color: var(--ifm-color-primary); + box-shadow: 0 0 0 2px var(--ifm-color-primary-light); +} +``` + +--- + +## Recommended Approach for Yellow Network + +Given your requirements (current v0.5.0, preparing for v0.6.0), I recommend: + +### 1. **Use Standard Docusaurus Versioning** +- It's well-documented and widely used +- Perfect for your 2-3 version use case +- Built-in CLI support + +### 2. **Version Strategy** +``` +docs/ → v0.6.0 (development/next) +versioned_docs/v0.5.0/ → v0.5.0 (current stable) +``` + +### 3. **Hide Development Version Initially** +- Set `includeCurrentVersion: false` until v0.6.0 is ready +- Or label it as "dev" and show an "unreleased" banner + +### 4. **Keep Versions Limited** +- Docusaurus recommends <10 versions +- For a new project, maintain only 2-3 versions max +- Archive older versions to static deployments if needed + +--- + +## Migration Strategy: 0.5.0 → 0.6.0 + +### Phase 1: Setup Versioning (Do Now) + +```bash +# 1. Install any missing dependencies +npm install + +# 2. Create your first version snapshot +npm run docusaurus docs:version 0.5.0 + +# 3. Verify structure +ls -la +# Should see: versions.json, versioned_docs/, versioned_sidebars/ +``` + +### Phase 2: Configure (Do Now) + +Update `docusaurus.config.js`: +```javascript +// Set current stable as default +lastVersion: '0.5.0', +versions: { + current: { + label: 'v0.6.0-dev', + path: 'next', + banner: 'unreleased', + }, + '0.5.0': { + label: 'v0.5.0', + path: '', // default path + }, +}, +``` + +### Phase 3: Development (Ongoing) + +- Continue all v0.6.0 work in `docs/` folder +- Any v0.5.0 hotfixes go in `versioned_docs/version-0.5.0/` +- Build locally to verify both versions work + +### Phase 4: Release v0.6.0 (When Ready) + +```bash +# 1. Freeze current docs as v0.6.0 +npm run docusaurus docs:version 0.6.0 + +# 2. Update config to make v0.6.0 the new default +# Change lastVersion: '0.6.0' + +# 3. Optionally remove older versions if no longer needed +# Delete from versions.json and remove folder +``` + +--- + +## Quick Reference: CLI Commands + +```bash +# Create a new version +npm run docusaurus docs:version + +# Example: Create v0.5.0 +npm run docusaurus docs:version 0.5.0 + +# Build to verify all versions +npm run build + +# Start dev server with all versions +npm run start + +# Clear cache if issues arise +npm run docusaurus clear +``` + +--- + +## Key Configuration Options Summary + +| Option | Purpose | Example | +|--------|---------|---------| +| `lastVersion` | Default version shown | `'0.5.0'` | +| `includeCurrentVersion` | Show dev version | `true/false` | +| `onlyIncludeVersions` | Limit versions built | `['current', '0.5.0']` | +| `versions.X.label` | Display name | `'v0.5.0'` | +| `versions.X.path` | URL path | `''` (root) or `'0.5.0'` | +| `versions.X.banner` | Warning banner | `'none'`, `'unreleased'`, `'unmaintained'` | +| `versions.X.badge` | Show version badge | `true/false` | + +--- + +## References + +- [Docusaurus Official Versioning Guide](https://docusaurus.io/docs/versioning) +- [Docusaurus Theme Configuration](https://docusaurus.io/docs/api/themes/configuration) +- [Consensys Docs Versioning Guide](https://docs-template.consensys.io/configure/versioning) +- [Spectro Cloud Git-based Versioning](https://www.spectrocloud.com/blog/when-docs-and-a-dinosaur-git-along-enabling-versioning-in-docusaurus) +- [Docusaurus Tutorial - Manage Versions](https://tutorial.docusaurus.io/docs/tutorial-extras/manage-docs-versions/) From f930e218eaed3fb1e72f66e084c2dc30f3e4620c Mon Sep 17 00:00:00 2001 From: Maharshi Mishra Date: Fri, 12 Dec 2025 16:36:58 +0530 Subject: [PATCH 2/2] docs: remove Docusaurus versioning guide markdown file --- temp/docusaurus-versioning-guide.md | 606 ---------------------------- 1 file changed, 606 deletions(-) delete mode 100644 temp/docusaurus-versioning-guide.md diff --git a/temp/docusaurus-versioning-guide.md b/temp/docusaurus-versioning-guide.md deleted file mode 100644 index a184a11..0000000 --- a/temp/docusaurus-versioning-guide.md +++ /dev/null @@ -1,606 +0,0 @@ -# Docusaurus Version Switcher Implementation Guide -## Comprehensive Research for Yellow Network Documentation - ---- - -## Table of Contents -1. [Executive Summary](#executive-summary) -2. [Industry Standard Approaches](#industry-standard-approaches) -3. [Folder Structure for Versioning](#folder-structure-for-versioning) -4. [Implementation Steps](#implementation-steps) -5. [Configuration Examples](#configuration-examples) -6. [Matching Your Figma Wireframe](#matching-your-figma-wireframe) -7. [Recommended Approach for Yellow Network](#recommended-approach) -8. [Migration Strategy: 0.5.0 → 0.6.0](#migration-strategy) - ---- - -## Executive Summary - -Based on my research, Docusaurus provides built-in versioning capabilities that create a version dropdown in the navbar. The industry standard approach involves: - -1. **`versions.json`** file - Lists all available versions -2. **`versioned_docs/`** folder - Contains frozen documentation for each version -3. **`versioned_sidebars/`** folder - Contains sidebar configs per version -4. **`docs/`** folder - Always contains the "current" (next/development) version - -For your Yellow Network docs currently at v0.5.0, you'll want to set up versioning that allows users to switch between stable releases (like the wireframe shows with "v0.53"). - ---- - -## Industry Standard Approaches - -### Approach 1: Standard Docusaurus Versioning (Recommended for most cases) - -This is used by Facebook, Docusaurus itself, Jest, and many major projects. - -**How it works:** -- `docs/` folder = "current" version (labeled "Next" by default) -- When you release, run `npm run docusaurus docs:version X.X.X` -- Creates `versioned_docs/version-X.X.X/` with a copy of all docs -- Creates `versioned_sidebars/version-X.X.X-sidebars.json` -- Updates `versions.json` - -**Pros:** -- Simple to implement -- Built-in CLI commands -- Automatic version dropdown -- Page-aware version switching (stays on same page when switching versions) - -**Cons:** -- Duplicates files (can bloat repo for large docs) -- Build times increase with each version - -### Approach 2: Git Branch-Based Versioning (Used by Spectro Cloud) - -**How it works:** -- Each version lives in a separate git branch -- CI/CD builds and deploys each branch separately -- Custom version switcher redirects between deployed sites - -**Pros:** -- No file duplication in repo -- Cleaner git history -- Smaller repo size - -**Cons:** -- More complex CI/CD setup -- Harder to maintain consistency across versions -- Requires custom version switcher implementation - -### Approach 3: Hybrid - Version Labels Without Duplication (Used by Consensys) - -**How it works:** -- Single `docs/` folder for the "current" stable version -- Configure `lastVersion: 'current'` to avoid "Next" label -- Version label configured in `docusaurus.config.js` - -**Pros:** -- Simpler structure -- No file duplication -- Good for projects where older versions aren't maintained - -**Cons:** -- Only practical if you don't need to maintain multiple versions simultaneously - ---- - -## Folder Structure for Versioning - -### Standard Versioned Site Structure - -``` -yellow-docs/ -├── docs/ # Current (development/next) version -│ ├── learn/ -│ │ └── introduction.md -│ ├── build/ -│ │ └── getting-started.md -│ ├── manuals/ -│ │ └── protocol-guide.md -│ ├── tutorials/ -│ │ └── quickstart.md -│ └── api-reference/ -│ └── nitrolite-api.md -│ -├── versioned_docs/ # Frozen versions -│ ├── version-0.5.0/ -│ │ ├── learn/ -│ │ ├── build/ -│ │ ├── manuals/ -│ │ ├── tutorials/ -│ │ └── api-reference/ -│ │ -│ └── version-0.4.0/ # (if maintaining older versions) -│ ├── learn/ -│ └── ... -│ -├── versioned_sidebars/ # Sidebar configs per version -│ ├── version-0.5.0-sidebars.json -│ └── version-0.4.0-sidebars.json -│ -├── versions.json # List of versions ["0.5.0", "0.4.0"] -├── sidebars.js # Sidebar for current version -├── docusaurus.config.js # Main configuration -└── package.json -``` - -### versions.json Format - -```json -[ - "0.5.0", - "0.4.0" -] -``` - -Note: Versions are ordered from newest to oldest. The first version is considered the "latest" stable version. - ---- - -## Implementation Steps - -### Step 1: Add Version Dropdown to Navbar - -In `docusaurus.config.js`, add the `docsVersionDropdown` item to your navbar: - -```javascript -module.exports = { - themeConfig: { - navbar: { - // Your existing logo config - logo: { - alt: 'Yellow Network', - src: 'img/yellow-logo.svg', - }, - items: [ - // Existing items... - { - type: 'docsVersionDropdown', - position: 'left', // Position as shown in your Figma (top-left under logo) - dropdownActiveClassDisabled: true, - // Optional: Add "All versions" link - dropdownItemsAfter: [ - { - to: '/versions', - label: 'All versions', - }, - ], - }, - // Other navbar items... - ], - }, - }, -}; -``` - -### Step 2: Configure Docs Plugin with Versioning - -```javascript -module.exports = { - presets: [ - [ - '@docusaurus/preset-classic', - { - docs: { - sidebarPath: require.resolve('./sidebars.js'), - // Enable editing - editUrl: 'https://github.com/layer-3/docs/tree/master/', - - // Versioning configuration - lastVersion: '0.5.0', // This will be the default/latest version - - // Optional: Don't show "current" (development) version publicly - includeCurrentVersion: true, // Set to false to hide development docs - - versions: { - current: { - label: '0.6.0-dev', // Label for unreleased/development version - path: 'next', // URL path: /docs/next/ - banner: 'unreleased', // Show "unreleased" banner - }, - '0.5.0': { - label: 'v0.5.0', // Displayed in dropdown - path: '', // Default path: /docs/ - banner: 'none', // No banner for stable - }, - // Add more versions as needed - }, - }, - }, - ], - ], -}; -``` - -### Step 3: Create Your First Version - -When you're ready to release v0.5.0: - -```bash -# This creates versioned_docs/version-0.5.0/ and updates versions.json -npm run docusaurus docs:version 0.5.0 -``` - -### Step 4: Prepare for Next Version (0.6.0) - -After running the version command: -- `docs/` folder now represents v0.6.0 (development) -- `versioned_docs/version-0.5.0/` contains the frozen v0.5.0 docs -- Continue working on `docs/` for v0.6.0 features - ---- - -## Configuration Examples - -### Complete docusaurus.config.js Example - -```javascript -const config = { - title: 'Yellow Network', - tagline: 'Decentralized Clearing Network', - url: 'https://docs.yellow.org', - baseUrl: '/', - - presets: [ - [ - '@docusaurus/preset-classic', - { - docs: { - sidebarPath: require.resolve('./sidebars.js'), - editUrl: 'https://github.com/layer-3/docs/tree/master/', - routeBasePath: '/', // Docs at root URL - - // Versioning - lastVersion: '0.5.0', - includeCurrentVersion: true, - onlyIncludeVersions: ['current', '0.5.0'], // Limit versions for faster builds - - versions: { - current: { - label: 'v0.6.0 (dev)', - path: 'next', - banner: 'unreleased', - badge: true, - }, - '0.5.0': { - label: 'v0.5.0', - path: '', - banner: 'none', - badge: false, - }, - }, - }, - theme: { - customCss: require.resolve('./src/css/custom.css'), - }, - }, - ], - ], - - themeConfig: { - navbar: { - logo: { - alt: 'Yellow Network', - src: 'img/yellow-logo.svg', - }, - items: [ - // Version dropdown - matches your Figma wireframe placement - { - type: 'docsVersionDropdown', - position: 'left', - dropdownActiveClassDisabled: true, - }, - // Main navigation items - { - type: 'docSidebar', - sidebarId: 'learnSidebar', - position: 'left', - label: 'Learn', - }, - { - type: 'docSidebar', - sidebarId: 'buildSidebar', - position: 'left', - label: 'Build', - }, - { - type: 'docSidebar', - sidebarId: 'manualsSidebar', - position: 'left', - label: 'Manuals', - }, - { - type: 'docSidebar', - sidebarId: 'tutorialsSidebar', - position: 'left', - label: 'Tutorials', - }, - { - type: 'docSidebar', - sidebarId: 'apiSidebar', - position: 'left', - label: 'API Reference', - }, - // GitHub link - { - href: 'https://github.com/layer-3/docs', - position: 'right', - className: 'header-github-link', - 'aria-label': 'GitHub repository', - }, - ], - }, - - // Optional: Version announcement bar - announcementBar: { - id: 'version_announcement', - content: '📢 v0.5.0 is now available! See what\'s new', - backgroundColor: '#FFEC00', // Yellow Network brand color - textColor: '#000', - isCloseable: true, - }, - }, -}; - -module.exports = config; -``` - ---- - -## Matching Your Figma Wireframe - -Based on the wireframe you provided, here's how to achieve the exact look: - -### Sidebar Layout (Left Panel) -``` -┌─────────────────────────────┐ -│ yellow. │ ← Logo -├─────────────────────────────┤ -│ 🐙 v0.53 ▼ │ ← GitHub icon + Version dropdown -├─────────────────────────────┤ -│ Learn │ -│ Build │ -│ Manuals │ -│ Tutorials │ -│ API Reference │ -│ Legacy │ -└─────────────────────────────┘ -``` - -### Custom Sidebar Component for Version Switcher - -To get the exact layout from your Figma (GitHub icon + version dropdown in sidebar), create a custom sidebar component: - -```jsx -// src/theme/DocSidebar/index.js (swizzle the sidebar) -import React from 'react'; -import OriginalSidebar from '@theme-original/DocSidebar'; -import { - useVersions, - useActiveVersion, -} from '@docusaurus/plugin-content-docs/client'; -import styles from './styles.module.css'; - -function VersionSwitcher() { - const versions = useVersions(); - const activeVersion = useActiveVersion(); - - return ( -
- - - - - - -
- ); -} - -export default function DocSidebarWrapper(props) { - return ( - <> - - - - ); -} -``` - -### Custom CSS for Sidebar Version Switcher - -```css -/* src/theme/DocSidebar/styles.module.css */ - -.versionSwitcher { - display: flex; - align-items: center; - gap: 8px; - padding: 12px 16px; - border-bottom: 1px solid var(--ifm-color-emphasis-200); - margin-bottom: 8px; -} - -.githubLink { - display: flex; - align-items: center; - color: var(--ifm-color-emphasis-700); - transition: color 0.2s; -} - -.githubLink:hover { - color: var(--ifm-color-primary); -} - -.versionSelect { - background: var(--ifm-background-surface-color); - border: 1px solid var(--ifm-color-emphasis-300); - border-radius: 4px; - font-size: 14px; - font-weight: 500; - cursor: pointer; - padding: 6px 12px; - color: var(--ifm-font-color-base); -} - -.versionSelect:hover { - border-color: var(--ifm-color-primary); -} - -.versionSelect:focus { - outline: none; - border-color: var(--ifm-color-primary); - box-shadow: 0 0 0 2px var(--ifm-color-primary-light); -} -``` - ---- - -## Recommended Approach for Yellow Network - -Given your requirements (current v0.5.0, preparing for v0.6.0), I recommend: - -### 1. **Use Standard Docusaurus Versioning** -- It's well-documented and widely used -- Perfect for your 2-3 version use case -- Built-in CLI support - -### 2. **Version Strategy** -``` -docs/ → v0.6.0 (development/next) -versioned_docs/v0.5.0/ → v0.5.0 (current stable) -``` - -### 3. **Hide Development Version Initially** -- Set `includeCurrentVersion: false` until v0.6.0 is ready -- Or label it as "dev" and show an "unreleased" banner - -### 4. **Keep Versions Limited** -- Docusaurus recommends <10 versions -- For a new project, maintain only 2-3 versions max -- Archive older versions to static deployments if needed - ---- - -## Migration Strategy: 0.5.0 → 0.6.0 - -### Phase 1: Setup Versioning (Do Now) - -```bash -# 1. Install any missing dependencies -npm install - -# 2. Create your first version snapshot -npm run docusaurus docs:version 0.5.0 - -# 3. Verify structure -ls -la -# Should see: versions.json, versioned_docs/, versioned_sidebars/ -``` - -### Phase 2: Configure (Do Now) - -Update `docusaurus.config.js`: -```javascript -// Set current stable as default -lastVersion: '0.5.0', -versions: { - current: { - label: 'v0.6.0-dev', - path: 'next', - banner: 'unreleased', - }, - '0.5.0': { - label: 'v0.5.0', - path: '', // default path - }, -}, -``` - -### Phase 3: Development (Ongoing) - -- Continue all v0.6.0 work in `docs/` folder -- Any v0.5.0 hotfixes go in `versioned_docs/version-0.5.0/` -- Build locally to verify both versions work - -### Phase 4: Release v0.6.0 (When Ready) - -```bash -# 1. Freeze current docs as v0.6.0 -npm run docusaurus docs:version 0.6.0 - -# 2. Update config to make v0.6.0 the new default -# Change lastVersion: '0.6.0' - -# 3. Optionally remove older versions if no longer needed -# Delete from versions.json and remove folder -``` - ---- - -## Quick Reference: CLI Commands - -```bash -# Create a new version -npm run docusaurus docs:version - -# Example: Create v0.5.0 -npm run docusaurus docs:version 0.5.0 - -# Build to verify all versions -npm run build - -# Start dev server with all versions -npm run start - -# Clear cache if issues arise -npm run docusaurus clear -``` - ---- - -## Key Configuration Options Summary - -| Option | Purpose | Example | -|--------|---------|---------| -| `lastVersion` | Default version shown | `'0.5.0'` | -| `includeCurrentVersion` | Show dev version | `true/false` | -| `onlyIncludeVersions` | Limit versions built | `['current', '0.5.0']` | -| `versions.X.label` | Display name | `'v0.5.0'` | -| `versions.X.path` | URL path | `''` (root) or `'0.5.0'` | -| `versions.X.banner` | Warning banner | `'none'`, `'unreleased'`, `'unmaintained'` | -| `versions.X.badge` | Show version badge | `true/false` | - ---- - -## References - -- [Docusaurus Official Versioning Guide](https://docusaurus.io/docs/versioning) -- [Docusaurus Theme Configuration](https://docusaurus.io/docs/api/themes/configuration) -- [Consensys Docs Versioning Guide](https://docs-template.consensys.io/configure/versioning) -- [Spectro Cloud Git-based Versioning](https://www.spectrocloud.com/blog/when-docs-and-a-dinosaur-git-along-enabling-versioning-in-docusaurus) -- [Docusaurus Tutorial - Manage Versions](https://tutorial.docusaurus.io/docs/tutorial-extras/manage-docs-versions/)