diff --git a/src/pages/assets/sidenav.png b/src/pages/assets/sidenav.png index 27e9502..6d67b6a 100644 Binary files a/src/pages/assets/sidenav.png and b/src/pages/assets/sidenav.png differ diff --git a/src/pages/assets/sitewidebanner.png b/src/pages/assets/sitewidebanner.png new file mode 100644 index 0000000..2d23284 Binary files /dev/null and b/src/pages/assets/sitewidebanner.png differ diff --git a/src/pages/assets/topnav.png b/src/pages/assets/topnav.png index cffc1b8..ca8dd13 100644 Binary files a/src/pages/assets/topnav.png and b/src/pages/assets/topnav.png differ diff --git a/src/pages/assets/topnav_dropdown.png b/src/pages/assets/topnav_dropdown.png deleted file mode 100644 index d4f6789..0000000 Binary files a/src/pages/assets/topnav_dropdown.png and /dev/null differ diff --git a/src/pages/blocks/accordion/accordion-basic.md b/src/pages/blocks/accordion/accordion-basic.md deleted file mode 100644 index 81a06c2..0000000 --- a/src/pages/blocks/accordion/accordion-basic.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Basic Accordion Block -description: Simple accordion example with collapsible text sections. ---- - -# Basic Accordion Example - -This example shows a simple accordion with just heading and text content, perfect for FAQs or simple collapsible sections. - - - -### What is this accordion component? - -This is a collapsible content section that can expand and collapse when users click on the heading. It's useful for organizing large amounts of information in a compact, user-friendly way. - - - -### How does it work? - -The accordion component allows you to hide and show content dynamically. When a user clicks on a heading, the corresponding content panel toggles between visible and hidden states. - - - -### Can I use multiple accordions? - -Yes, you can include as many accordion items as needed on a single page. Each item operates independently, allowing users to expand or collapse sections based on their interests. - - - -### What are the benefits? - -Accordions help reduce page clutter by condensing information into expandable sections. This improves readability and helps users focus on the content that matters most to them. - -## Usage - -Use `slots` to identify the markdown content: - -- `heading` (required) - The title of the accordion item -- `text` (required) - The body content - -Each `` component creates a collapsible section that users can expand or collapse by clicking on the heading. - diff --git a/src/pages/blocks/accordion/accordion-with-table-and-code.md b/src/pages/blocks/accordion/accordion-with-table-and-code.md deleted file mode 100644 index d23e91b..0000000 --- a/src/pages/blocks/accordion/accordion-with-table-and-code.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Accordion Block with Table and Code -description: Complex accordion example with tables and code blocks for detailed technical documentation. ---- - -# Accordion with Table and Code Example - -This example demonstrates a complex accordion with multiple content types including tables, text descriptions, and code blocks. This is ideal for displaying structured data or step-by-step processes. - -Each step shown in the following accordion is described in detail below. Each description includes sample data that demonstrates the different content types available. - -## Accordion Heading - - - -### 1. Initial Setup - -| Step | Description | Duration | Status | Endpoint | -| --- | --- | --- | --- | --- | -| 1 | User initiates the process and the system begins loading resources | 0s | Starting | `/api/initialize` | - -This action represents the beginning of a workflow. The system state transitions from idle to active. A unique identifier is generated and returned to the client for tracking purposes. This identifier will be used in subsequent steps. - -```json -{ - "eventType": "process.start", - "timestamp": "2024-01-15T10:00:00.000Z", - "data": { - "sessionId": "abc123", - "config": { - "name": "Sample Process", - "timeout": 60, - "mode": "standard", - "version": "1.0.0" - } - } -} -``` - - - -### 2. Loading Phase - -| Step | Description | Duration | Status | Endpoint | -| --- | --- | --- | --- | --- | -| 2 | System enters loading state while gathering resources | 1s | Loading | `/api/loading` | - -The process enters a waiting state while necessary resources are retrieved. Progress indicators may be displayed to the user during this phase. - -```json -{ - "eventType": "state.loading", - "timestamp": "2024-01-15T10:00:01.000Z", - "data": { - "sessionId": "abc123", - "progress": 0 - } -} -``` - - - -### 3. Status Check - -| Step | Description | Duration | Status | Endpoint | -| --- | --- | --- | --- | --- | -| 3 | Periodic status update is transmitted | 10s | Active | `/api/heartbeat` | - -A routine status signal is sent to maintain the connection and confirm system health. - - - - -### 4. User Pause - -| Step | Description | Duration | Status | Endpoint | -| --- | --- | --- | --- | --- | -| 4 | User initiates a pause action | 15s | Paused | `/api/pause` | - -The user triggers a pause action, temporarily halting the current process. - -```json -{ - "eventType": "action.pause", - "timestamp": "2024-01-15T10:00:15.000Z", - "data": { - "sessionId": "abc123", - "counter": 12 - } -} -``` - - - -### 5. End Session - -| Step | Description | Duration | Status | Endpoint | -| --- | --- | --- | --- | --- | -| 5 | User terminates the session before completion | 29s | Ended | `/api/end` | - -The user exits the application. A termination signal is sent to close the session immediately. - -```json -{ - "eventType": "process.end", - "timestamp": "2024-01-15T10:00:29Z", - "data": { - "sessionId": "abc123", - "counter": 17 - } -} -``` - -## Usage - -Use `slots` to identify the markdown content for each ``: - -- `heading` (required) - The title of the accordion item -- `table` (optional) - Tabular data -- `text` (optional) - Body text with descriptions -- `code` (optional) - Code blocks with examples - -You can mix and match slots based on your content needs. Each accordion item can have different slot combinations. - diff --git a/src/pages/blocks/accordion/index.md b/src/pages/blocks/accordion/index.md index 6d1a77a..2cabafb 100644 --- a/src/pages/blocks/accordion/index.md +++ b/src/pages/blocks/accordion/index.md @@ -5,34 +5,80 @@ description: Learn how to use the Accordion block to create collapsible content # Accordion Block -Create collapsible content sections to organize information. Each accordion item can be expanded or collapsed individually. +Collapsible content sections. ## Syntax ```markdown - + -Content goes here. +### Section heading - +Content goes here. ``` ## Parameters -- **header**: Title/header of the accordion item (required) -- **slots**: Content structure - - `"heading, text"`: Basic text content - - `"heading, text, table"`: Include tables - - `"heading, text, code"`: Include code blocks +- **slots**: Content types + - `"heading, text"` - Text only + - `"heading, text, table"` - With tables + - `"heading, text, code"` - With code blocks + - Mix and match as needed + +## Examples + +### Basic Accordion + + + +#### What is this accordion component? + +This is a collapsible content section that can expand and collapse when users click on the heading. It's useful for organizing large amounts of information in a compact, user-friendly way. + + + +#### How does it work? + +The accordion component allows you to hide and show content dynamically. When a user clicks on a heading, the corresponding content panel toggles between visible and hidden states. + + + +#### Can I use multiple accordions? + +Yes, you can include as many accordion items as needed on a single page. Each item operates independently, allowing users to expand or collapse sections based on their interests. + +### With Table and Code + + + +#### 1. Initial Setup + +| Step | Description | Duration | Status | Endpoint | +| --- | --- | --- | --- | --- | +| 1 | User initiates the process and the system begins loading resources | 0s | Starting | `/api/initialize` | + +This action represents the beginning of a workflow. The system state transitions from idle to active. + +```json +{ + "eventType": "process.start", + "timestamp": "2024-01-15T10:00:00.000Z", + "data": { + "sessionId": "abc123", + "config": { + "name": "Sample Process", + "timeout": 60 + } + } +} +``` -## Variants + -- [Basic Accordion](accordion-basic.md) - Simple collapsible text sections -- [Accordion with Table and Code](accordion-with-table-and-code.md) - Complex content with tables and code +#### 2. Status Check -## Best Practices +| Step | Description | Duration | Status | Endpoint | +| --- | --- | --- | --- | --- | +| 3 | Periodic status update is transmitted | 10s | Active | `/api/heartbeat` | -- Use clear, descriptive headings -- Keep individual sections focused -- Group related information together -- Place most important content in first item +A routine status signal is sent to maintain the connection and confirm system health. diff --git a/src/pages/blocks/announcement/announcement-button-only.md b/src/pages/blocks/announcement/announcement-button-only.md deleted file mode 100644 index 5c7a018..0000000 --- a/src/pages/blocks/announcement/announcement-button-only.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Button-Only Announcement -description: Simple centered call-to-action button without heading or text. ---- - -# Button-Only Announcement Example - -This example shows a minimal announcement with just a centered button, perfect for simple call-to-action prompts. - - - -- [Click Here](https://example.com) - - - -- [Click Here](https://example.com) - -## Usage - -Use `slots` to identify the markdown content: - -- `button` (required) - Call-to-action link - -Available attributes: - -- `variant` - Set to `primary` or `secondary` (default: `primary`) - diff --git a/src/pages/blocks/announcement/announcement-with-heading.md b/src/pages/blocks/announcement/announcement-with-heading.md deleted file mode 100644 index 204335e..0000000 --- a/src/pages/blocks/announcement/announcement-with-heading.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Announcement Block with Heading -description: Full announcement with title, description, and action button. ---- - -# Announcement with Heading Examples - -This example shows full-featured announcements with heading, descriptive text, and an action button. You can customize the variant and background color. - -## Secondary Variant (Subtle) - - - -### Lorem Ipsum Dolor Sit - -Consectetur adipiscing elit sed do eiusmod tempor incididunt ut labore. - -- [Read more details](https://example.com) - -## Primary Variant (Prominent) - - - -### Amet Consectetur Adipiscing - -Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. - -- [View full content](https://example.com) - -## White Background - - - -### Eiusmod Tempor Incididunt - -Ut labore et dolore magna aliqua enim ad minim veniam quis nostrud. - -- [Learn more here](https://example.com) - -## Usage - -Use `slots` to identify the markdown content: - -- `heading` (optional) - The title of the announcement -- `text` (optional) - The descriptive content -- `button` (optional) - Call-to-action link - -Available attributes: - -- `variant` - Set to `primary` or `secondary` (default: `primary`) -- `backgroundColor` - Set to `background-color-gray` or `background-color-white` (default: `background-color-gray`) - diff --git a/src/pages/blocks/announcement/index.md b/src/pages/blocks/announcement/index.md index 5c6354e..5fe1db5 100644 --- a/src/pages/blocks/announcement/index.md +++ b/src/pages/blocks/announcement/index.md @@ -5,38 +5,52 @@ description: Display important announcements and notices to your users with the # Announcement Block -Display important notices, updates, or calls-to-action at the top of your pages. - - - -Note: The Announcement block replaces the Teaser block that was previously used in Gatsby. +Display notices, updates, or calls-to-action. ## Syntax ```markdown - + ``` ## Parameters -- **slots**: Content structure - - `"heading, text, button"`: Full announcement with all elements - - `"button"`: Button-only announcement +- **slots**: + - `"heading, text, button"` - Full announcement + - `"button"` - Button only + +- **variant**: Style + - `"primary"` - Bold (default) + - `"secondary"` - Subtle + +- **backgroundColor**: Background + - `"background-color-gray"` + - `"background-color-white"` (default) + +## Examples + +### Full Announcement + + + +#### New Release Available + +Check out the latest features and improvements in version 2.0. + +- [Read more](https://example.com) + +### Button Only + + -- **variant**: Style variant - - `"primary"`: Bold, prominent (default) - - `"secondary"`: Subtle +- [Get Started](https://example.com) -- **position**: `"center"` for centered button-only announcements +### Primary Variant -## Variants + -- [Announcement with Heading](announcement-with-heading.md) - Full announcement with title and description -- [Button-only Announcement](announcement-button-only.md) - Simple call-to-action button +#### Important Update -## Best Practices +Review these changes before your next deployment. -- Use for important site-wide notices -- Keep text concise and actionable -- Limit to one announcement per page -- Use primary variant for critical updates +- [View details](https://example.com) diff --git a/src/pages/blocks/breadcrumb/index.md b/src/pages/blocks/breadcrumb/index.md index 59dc9f1..7bfe781 100644 --- a/src/pages/blocks/breadcrumb/index.md +++ b/src/pages/blocks/breadcrumb/index.md @@ -5,34 +5,19 @@ description: Automatically generated navigation trail based on TopNav and SideNa # Breadcrumbs -Breadcrumbs provide users with a hierarchical navigation trail showing their current location within the documentation site structure. +Auto-generated navigation trail from your TopNav and SideNav. -## Overview +## How It Works -Breadcrumbs are **automatically generated** based on your TopNav and SideNav configuration. They require no separate configuration or setup - the breadcrumb trail is built dynamically from your existing navigation structure defined in `config.md`. - -## How Breadcrumbs Work - -The breadcrumb trail is constructed by combining: - -1. **TopNav** - Provides the top-level navigation context -2. **SideNav** - Provides the hierarchical page structure - -As users navigate through your documentation, breadcrumbs automatically update to reflect their current position in the site hierarchy. - -## Example - -The breadcrumb trail is automatically generated from: -- **TopNav**: Products > Overview > Reference Docs (top-level sections) -- **SideNav**: Overview > Configuration Blocks > Breadcrumbs +Breadcrumbs are built automatically from your `config.md` navigation structure: +- **TopNav**: Top-level context +- **SideNav**: Page hierarchy ![breadcrumb](../../assets/breadcrumb.png) -## Configuration - -Breadcrumbs are configured through your `config.md` file's navigation structure: +## Example -```markdown +```yaml - pages: - [Overview](index.md) - [Reference Docs](blocks/index.md) @@ -45,17 +30,7 @@ Breadcrumbs are configured through your `config.md` file's navigation structure: - [Breadcrumbs](/blocks/breadcrumb/index.md) ``` -This navigation structure automatically generates breadcrumbs for each page based on its position in the hierarchy. - -## Best Practices - -- **Maintain clear hierarchy**: Organize your `config.md` with logical parent-child relationships -- **Use descriptive titles**: Breadcrumb text is taken from the link titles in your navigation -- **Avoid deep nesting**: Keep navigation depth to 3-4 levels for optimal user experience -- **Test navigation paths**: Verify that breadcrumbs accurately reflect the intended page hierarchy - -## Related Configuration - -- [TopNav](/blocks/topnav/index.md) - Configure the top navigation bar -- [SideNav](/blocks/sidenav/index.md) - Configure the side navigation menu +## Related +- [TopNav](/blocks/topnav/index.md) - Top navigation +- [SideNav](/blocks/sidenav/index.md) - Side navigation diff --git a/src/pages/blocks/code/code-basic.md b/src/pages/blocks/code/code-basic.md index b34f490..302c6ef 100644 --- a/src/pages/blocks/code/code-basic.md +++ b/src/pages/blocks/code/code-basic.md @@ -44,9 +44,3 @@ function greet(name) { console.log(greet("World")); ``` - -## Best Practices - -- Always specify a language for syntax highlighting -- Use for straightforward code examples -- Keep code blocks concise and focused diff --git a/src/pages/blocks/code/code-highlighted-line.md b/src/pages/blocks/code/code-highlighted-line.md index 13187bd..4a409fc 100644 --- a/src/pages/blocks/code/code-highlighted-line.md +++ b/src/pages/blocks/code/code-highlighted-line.md @@ -35,9 +35,3 @@ function processData(input) { return null; } ``` - -## Best Practices - -- Highlight only the most important lines to avoid overwhelming the reader -- Use line ranges (e.g., `1-5`) for consecutive lines -- Set `data-line-offset` when showing excerpts from larger files diff --git a/src/pages/blocks/code/code-in-list.md b/src/pages/blocks/code/code-in-list.md index 4eaccea..5757216 100644 --- a/src/pages/blocks/code/code-in-list.md +++ b/src/pages/blocks/code/code-in-list.md @@ -60,9 +60,3 @@ Follow these steps to set up your development environment: ``` 1. Open your browser and navigate to `http://localhost:3000` - -## Best Practices - -- Indent code blocks with 4 spaces or 1 tab to nest within list items -- Use for step-by-step tutorials and installation guides -- Add explanatory text before and after code blocks for context diff --git a/src/pages/blocks/code/code-in-table.md b/src/pages/blocks/code/code-in-table.md index 18cb995..174796f 100644 --- a/src/pages/blocks/code/code-in-table.md +++ b/src/pages/blocks/code/code-in-table.md @@ -30,9 +30,3 @@ Use backticks for inline code in table cells: | `email` | `string` | User's email address | | `createdAt` | `Date` | Timestamp when the user was created | | `isActive` | `boolean` | Whether the user account is active | - -## Best Practices - -- Use inline code for property names, types, and values -- Keep table formatting clean and aligned -- Ideal for API reference documentation diff --git a/src/pages/blocks/code/code-overload.md b/src/pages/blocks/code/code-overload.md index c424cbf..b9c6fb2 100644 --- a/src/pages/blocks/code/code-overload.md +++ b/src/pages/blocks/code/code-overload.md @@ -55,10 +55,3 @@ npm test # Build for production npm run build ``` - -## Best Practices - -- Use combined features sparingly - only when necessary -- Keep attribute combinations logical and purposeful -- Test complex code blocks to ensure they render correctly -- Consider if simpler alternatives would be more readable diff --git a/src/pages/blocks/code/index.md b/src/pages/blocks/code/index.md index 58f30af..56c277f 100644 --- a/src/pages/blocks/code/index.md +++ b/src/pages/blocks/code/index.md @@ -71,12 +71,3 @@ See detailed examples and use cases: - [Code in Lists](code-in-list.md) - Code blocks nested in lists - [Code in Tables](code-in-table.md) - Inline code in table cells - [Combined Features](code-overload.md) - Multiple features together - -## Best Practices - -- Always specify a language for proper syntax highlighting -- Use `data-line` to highlight important code sections -- Use `disableLineNumbers` for short, simple commands -- Set `data-line-offset` when showing code excerpts from larger files -- Keep code snippets concise and focused - diff --git a/src/pages/blocks/codeblock/code-block-with-picklist.md b/src/pages/blocks/codeblock/code-block-with-picklist.md index 6c36939..11e6a15 100644 --- a/src/pages/blocks/codeblock/code-block-with-picklist.md +++ b/src/pages/blocks/codeblock/code-block-with-picklist.md @@ -102,9 +102,3 @@ start(); ```js // empty 2 ``` - -## Best Practices - -- Use descriptive language labels (e.g., file names or language names) -- Keep the number of options reasonable (typically 3-7) -- Order languages logically (e.g., HTML, CSS, JavaScript) diff --git a/src/pages/blocks/codeblock/code-block-without-picklist.md b/src/pages/blocks/codeblock/code-block-without-picklist.md index c7cb3dd..737be76 100644 --- a/src/pages/blocks/codeblock/code-block-without-picklist.md +++ b/src/pages/blocks/codeblock/code-block-without-picklist.md @@ -101,11 +101,4 @@ start(); ```js // empty 2 -``` - -## Best Practices - -- Use when you want all code blocks visible at once -- Ideal for showing progression or related files side-by-side -- Keep headings clear to distinguish between blocks - +``` \ No newline at end of file diff --git a/src/pages/blocks/codeblock/index.md b/src/pages/blocks/codeblock/index.md index 78bc6d6..f1e287f 100644 --- a/src/pages/blocks/codeblock/index.md +++ b/src/pages/blocks/codeblock/index.md @@ -38,11 +38,4 @@ Use the CodeBlock component when you need to: - Compare different file contents - Provide code examples in multiple languages with a picker -For single code snippets, use regular [markdown code blocks](../code/index.md) instead. - -## Best Practices - -- Use meaningful headings that describe each code block -- Group related code snippets together (e.g., request/response pairs) -- Specify languages for syntax highlighting when possible -- Use language picker for code examples in multiple programming languages +For single code snippets, use regular [markdown code blocks](../code/index.md) instead. \ No newline at end of file diff --git a/src/pages/blocks/column/index.md b/src/pages/blocks/column/index.md index 8465d97..b0b5c84 100644 --- a/src/pages/blocks/column/index.md +++ b/src/pages/blocks/column/index.md @@ -5,7 +5,7 @@ description: Create multi-column layouts for content organization using the Colu # Column Block -Create multi-column layouts to display content side-by-side with images, headings, text, and links. +Multi-column layouts for side-by-side content. ## Syntax @@ -15,46 +15,39 @@ Create multi-column layouts to display content side-by-side with images, heading ## Parameters -- **slots**: Content structure for each column - - `"heading, text"`: Heading and text - - `"image, heading, text"`: Image, heading, and text - - `"image, heading, text, buttons"`: All elements including links +- **slots**: Content per column + - `"heading, text"` - Text only + - `"image, heading, text"` - With image + - `"image, heading, text, buttons"` - With image and links -- **repeat**: Number of columns to display (typically 2-4) +- **repeat**: Number of columns (2-4) -- **Preferred Image Size**: 580 x 350 px for optimal display +- **Image size**: 580 x 350 px recommended ## Example - + ![Feature 1](../../assets/column.jpg) -### Feature Heading +### Feature One -Description of the feature or content. Keep text concise for better readability in column layouts. +Description of the first feature. [Learn more](https://example.com) ![Feature 2](../../assets/column2.jpg) -### Another Feature +### Feature Two -More details about this feature or capability. Column layouts work well for comparing options or showcasing multiple features. +Description of the second feature. [Learn more](https://example.com) ![Feature 3](../../assets/column3.jpg) -### Third Feature +### Feature Three -Additional content for the third column. Use consistent structure across all columns for visual balance. +Description of the third feature. [Learn more](https://example.com) - -## Best Practices - -- Keep column count to 2-4 for readability -- Use consistent content structure across all columns -- Keep text concise to maintain visual balance -- Use preferred image size of 580 x 350 px for consistency across columns diff --git a/src/pages/blocks/discoverblock/index.md b/src/pages/blocks/discoverblock/index.md index c8ce989..4aeacaf 100644 --- a/src/pages/blocks/discoverblock/index.md +++ b/src/pages/blocks/discoverblock/index.md @@ -5,7 +5,7 @@ description: Showcase featured content and resources using the Discover block co # Discover Block -Display featured content, resources, or links in a card-based layout. +Featured content in a card layout. ## Syntax @@ -22,123 +22,58 @@ Description text here. ## Parameters - **slots**: Content structure - - `"link, text"`: Link with description - - `"heading, link, text"`: Heading, link, and description - - `"image, heading, link, text"`: Icon/image, heading, link, and description + - `"link, text"` - Link with description + - `"heading, link, text"` - With heading + - `"image, heading, link, text"` - With image -- **width**: Card width (optional) - - Default: Full width - - `"25%"`: Quarter width (for grid layouts) - - `"33%"`: Third width - - `"50%"`: Half width +- **width**: Card width + - Full width (default) + - `"25%"` - Quarter (4-column grid) + - `"33%"` - Third (3-column grid) + - `"50%"` - Half (2-column grid) -## Image Suggestions - -For the `image` slot, use a **512 x 512 px** image for optimal display quality. +- **Image size**: 512 x 512 px recommended ## Examples -### Basic Discover Blocks +### Basic -## Get Started with Basics - -[Developer Quickstart Guide](https://example.com/quickstart) - -Start building your first application with our platform. - - - -[API Reference](https://example.com/api-reference) - -Explore the complete API documentation and endpoints. - - - -[Development Tools](https://example.com/tools) - -Access the essential tools to help you create, debug, and deploy your applications efficiently. +## Get Started - +[Developer Guide](https://example.com/quickstart) -[Code Samples](https://example.com/samples) - -Browse code examples to accelerate your development workflow. +Start building your first application. -[Migration Guide](https://example.com/migration) +[API Reference](https://example.com/api) -Transitioning from a previous version? Find migration resources here. +Explore the complete API documentation. - +### Grid Layout -[Design Guidelines](https://example.com/design) +Use `width="33%"` for a 3-column grid: -Learn best practices for creating user-friendly applications. - -### With Images and Grid Layout - -Use `width="25%"` to create a grid layout with multiple cards: - - + ![Community](../../assets/test-icon.png) -### Developer Community - -[Community forum](https://example.com/forum) - -Ask questions, share knowledge, and participate in discussions with other developers. - - - -[Developer portal](https://example.com/portal) - -Access your developer account, manage applications, and view analytics. - - - -![GitHub](../../assets/test-icon.png) - -### GitHub - -[Contributing](https://github.com/example/project/blob/main/.github/CONTRIBUTING.md) - -Learn how you can contribute to the project documentation. - - - -[Issues](https://github.com/example/project/issues) - -Submit an issue to the repository for the team to review. - - - -[Pull requests](https://github.com/example/project/pulls) - -View open pull requests for the repository. - - - -![Slack](../../assets/test-icon.png) +### Community -### Slack +[Forum](https://example.com/forum) -[Request an invite](https://example.com/slack-invite) +Ask questions and share knowledge. -Join our developer community Slack workspace to connect with other developers. + - +[Portal](https://example.com/portal) -[Developer channel](https://example.slack.com/channels/developers) +Manage your applications. -Connect with developers in our main community channel. + -## Best Practices +[Contributing](https://github.com/example/project) -- Use descriptive headings and concise text -- Use consistent image sizes (512 x 512 px recommended) -- Use `width="25%"` for 4-column grids, `"33%"` for 3-column -- Limit to 3-8 blocks for optimal scanning +Contribute to the project. diff --git a/src/pages/blocks/edition/edition-with-link.md b/src/pages/blocks/edition/edition-with-link.md deleted file mode 100644 index b98fd95..0000000 --- a/src/pages/blocks/edition/edition-with-link.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Edition Block with Link -description: Display edition-specific content with a clickable link. ---- - -# Edition with Link Example - - - -[Enterprise Edition](https://example.com/editions) - - - -Use `slot` to identify the markdown content: - -- `text` (required) - The edition text content with a link - -When you include a link in the text slot, the Edition block will render it as a clickable element, allowing users to navigate to the specified URL. - diff --git a/src/pages/blocks/edition/edition-with-no-link.md b/src/pages/blocks/edition/edition-with-no-link.md deleted file mode 100644 index 2cff82e..0000000 --- a/src/pages/blocks/edition/edition-with-no-link.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Edition Block without Link -description: Display edition-specific content as plain text. ---- - -# Edition without Link Example - - - -PaaS Only - - -Use `slot` to identify the markdown content: - -- `text` (required) - The edition text content - -When you provide plain text without a link, the Edition block will render it as a static label, useful for displaying edition or platform information. - diff --git a/src/pages/blocks/edition/index.md b/src/pages/blocks/edition/index.md index 9b375b4..083d960 100644 --- a/src/pages/blocks/edition/index.md +++ b/src/pages/blocks/edition/index.md @@ -5,7 +5,7 @@ description: Display edition-specific content using the Edition block component. # Edition Block -Display edition-specific labels or badges to indicate which platform or version content applies to. +Display edition or platform labels. ## Syntax @@ -17,16 +17,18 @@ Enterprise Edition ## Parameters -- **slots**: `"text"` - The edition text content +- **slots**: `"text"` - Edition text or link -## Variants +## Examples -- [Edition with Link](edition-with-link.md) - Display edition as a clickable link -- [Edition without Link](edition-with-no-link.md) - Display edition as plain text +### Plain Text -## Best Practices + -- Use clear, recognizable edition names -- Place at the beginning of content sections -- Keep text brief and scannable +PaaS Only +### With Link + + + +[Enterprise Edition](https://example.com/editions) diff --git a/src/pages/blocks/footer/index.md b/src/pages/blocks/footer/index.md index 6391c4b..53865fe 100644 --- a/src/pages/blocks/footer/index.md +++ b/src/pages/blocks/footer/index.md @@ -5,26 +5,11 @@ description: The footer component is centrally managed and appears at the bottom # Footer -The Footer component appears at the bottom of all documentation pages and is **centrally managed** to maintain consistency across Adobe Developer documentation sites. - -## Overview - -The footer automatically appears on all pages and includes: -- Navigation links and resources -- Legal and privacy information -- Social media links -- Adobe branding +The footer appears on all pages and is centrally managed. ## Configuration -The footer is **not directly configurable** by documentation authors. - -### Need to Change the Footer? - -Contact our team via Slack: **`#adobe-developer-website`** - -Provide details about your requested changes and the team will help with: -- Adding or updating links -- Modifying footer content -- Custom requirements for your project +The footer is **not directly configurable**. +To request changes, contact the team through slack on #adobe-developer-website with details about: +- Link and content updates diff --git a/src/pages/blocks/image/index.md b/src/pages/blocks/image/index.md index 1d56685..2fd542a 100644 --- a/src/pages/blocks/image/index.md +++ b/src/pages/blocks/image/index.md @@ -37,11 +37,3 @@ Display images in your documentation using standard markdown syntax. ![Platform interface](../../assets/image1.jpeg) ![External Image](https://images.unsplash.com/photo-1498050108023-c5249f4df085?w=1200&q=80) - -## Best Practices - -- Always include descriptive alt text for accessibility -- Use preferred image size of 580 x 350 px for optimal display -- Optimize images for web (< 500KB recommended) -- Use PNG for screenshots, JPG for photos, SVG for icons -- Store local images in `src/pages/assets/` directory diff --git a/src/pages/blocks/index.md b/src/pages/blocks/index.md index e238035..b7e865e 100644 --- a/src/pages/blocks/index.md +++ b/src/pages/blocks/index.md @@ -5,171 +5,143 @@ description: Explore all available blocks for the Adobe Developer documentation # DevDoc Block Examples -Explore all available blocks for creating rich, interactive documentation. Blocks are organized into two main categories: +Build rich, interactive documentation using blocks organized into two categories: -- **Configuration Blocks**: Define site structure and navigation (configured in `config.md`) -- **Content Blocks**: Create and format your documentation content +- **Configuration Blocks**: Site structure and navigation (set in `config.md`) +- **Content Blocks**: Page content and formatting ## Configuration Blocks -These blocks define the structure and navigation of your documentation site. They are configured in your `config.md` file and control the overall navigation experience. +Control your site's structure and navigation through `config.md`. -### SideNav +### [SideNav](sidenav/index.md) -[SideNav](sidenav/index.md) -Configure the side navigation menu for your documentation site. +Side navigation menu. -### TopNav +### [TopNav](topnav/index.md) -[TopNav](topnav/index.md) -Configure the top navigation bar for your documentation site. +Top navigation bar. -### Breadcrumbs +### [Breadcrumbs](breadcrumb/index.md) -[Breadcrumbs](breadcrumb/index.md) -Automatically generated navigation trail based on TopNav and SideNav configuration. +Auto-generated navigation trail from your TopNav and SideNav. -### Footer +### [Footer](footer/index.md) -[Footer](footer/index.md) -Centrally managed footer appearing on all pages. Contact the team via Slack (#adobe-developer-website) for changes. +Site footer (centrally managed). + +### [Site-Wide Banner](site-wide-banner/index.md) + +Announcement banner displayed across all pages. ## Content Blocks -All content presentation blocks for creating and organizing your documentation content. +Build and organize your page content. -### Accordion +### [Accordion](accordion/index.md) -[Accordion](accordion/index.md) -Collapsible content sections for organizing information. +Collapsible sections. -### Announcement +### [Announcement](announcement/index.md) -[Announcement](announcement/index.md) -Display important announcements or notices. +Important notices and announcements. -### Code +### [Code](code/index.md) -[Code](code/index.md) -Display code snippets using markdown code blocks with syntax highlighting and advanced features. -- [Basic Code Blocks](code/code-basic.md) - Simple code examples -- [Highlighted Lines](code/code-highlighted-line.md) - Specific line highlighting examples -- [Code in Lists](code/code-in-list.md) - Code blocks nested in lists -- [Code in Tables](code/code-in-table.md) - Inline code in table cells -- [Combined Features](code/code-overload.md) - Multiple features together +Markdown code snippet with syntax. +- [Basic](code/code-basic.md) - Simple examples +- [Highlighted Lines](code/code-highlighted-line.md) - Line highlighting +- [In Lists](code/code-in-list.md) - Nested in lists +- [In Tables](code/code-in-table.md) - Inline in tables +- [Combined Features](code/code-overload.md) - Multiple features -### CodeBlock +### [CodeBlock](codeblock/index.md) -[CodeBlock](codeblock/index.md) -Display multiple code snippets with headings using the CodeBlock component. -- [With Language Picker](codeblock/code-block-with-picklist.md) - Dropdown to switch languages -- [Without Language Picker](codeblock/code-block-without-picklist.md) - All blocks visible +Multiple code block with headings. +- [With Language Picker](codeblock/code-block-with-picklist.md) - Switch between languages +- [Without Language Picker](codeblock/code-block-without-picklist.md) - Show all at once -### Column +### [Column](column/index.md) -[Column](column/index.md) -Multi-column layouts for content organization. +Multi-column layouts. -### Discover Block +### [Discover Block](discoverblock/index.md) -[Discover Block](discoverblock/index.md) -Showcase featured content or resources. +Featured content showcase. -### Edition +### [Edition](edition/index.md) -[Edition](edition/index.md) -Edition-specific content display. +Edition-specific content. -### HeroSimple +### [HeroSimple](herosimple/herosimple-default.md) -[HeroSimple](herosimple/herosimple-default.md) -Simpler hero option for clean, focused pages. +Simple hero banner. - [Default](herosimple/herosimple-default.md) - [Full Width](herosimple/herosimple-fullwidth.md) - [Half Width](herosimple/herosimple-halfwidth.md) -### Image +### [Image](image/index.md) -[Image](image/index.md) -Image display and formatting examples. +Add and format images. -### Inline Alert +### [Inline Alert](inline-alert/index.md) -[Inline Alert](inline-alert/index.md) -Inline alert messages for warnings, tips, and notes. +Warnings, tips, and notes. -### Inline Code +### [Inline Code](inline-code/index.md) -[Inline Code](inline-code/index.md) -Format inline code snippets, variable names, and technical terms using backticks. +Format inline code with backticks. -### Links +### [Links](links/index.md) -[Links](links/index.md) -Learn how to create links between documentation pages using relative and absolute paths. +Link between pages using relative and absolute paths. -### List +### [List](list/index.md) -[List](list/index.md) -Styled lists with icons and formatting options. +Styled lists with icons. -### On This Page +### [On This Page](onthispage/index.md) -[On This Page](onthispage/index.md) -Automatic table of contents sidebar displaying H2 and H3 headings for in-page navigation. +Auto-generated table of contents from H2 and H3 headings. -### Redocly API Block +### [Redocly API Block](redoclyapiblock/redocly-api-block-default.md) -[Redocly API Block](redoclyapiblock/redocly-api-block-default.md) -Interactive API documentation from OpenAPI specifications. +Interactive API docs from OpenAPI specs. -**Configuration Options:** -- [Default](redoclyapiblock/redocly-api-block-default.md) - Standard configuration -- [Custom Configurations](redoclyapiblock/redocly-api-block-configs.md) - Customize styling and behavior +**Configuration:** +- [Default](redoclyapiblock/redocly-api-block-default.md) - Standard setup +- [Custom](redoclyapiblock/redocly-api-block-configs.md) - Styling and behavior -**Layout Options:** -- [Without Layout](redoclyapiblock/redocly-api-block-no-layout.md) - Full-page documentation -- [Without Sidebar](redoclyapiblock/redocly-api-block-no-sidebar.md) - Hide sidebar navigation -- [Without Sidebar & Search](redoclyapiblock/redocly-api-block-no-sidebar-no-search.md) - Minimalist view -- [With Scroll Offset](redoclyapiblock/redocly-api-block-no-y-scroll-offset.md) - For fixed headers +**Layout:** +- [Without Layout](redoclyapiblock/redocly-api-block-no-layout.md) - Full-page +- [Without Sidebar](redoclyapiblock/redocly-api-block-no-sidebar.md) - No sidebar +- [Without Sidebar & Search](redoclyapiblock/redocly-api-block-no-sidebar-no-search.md) - Minimal +- [With Scroll Offset](redoclyapiblock/redocly-api-block-no-y-scroll-offset.md) - Fixed headers **Advanced:** -- [External API Example](redoclyapiblock/redocly-overflow.md) - Load from external URLs - -### Resources - -[Resources](resources/resources.md) -Display resource links with optional hero banner. -- [With Hero](resources/resources.md) -- [Without Hero](resources/resources-with-no-hero.md) +- [External API](redoclyapiblock/redocly-overflow.md) - Load from URLs -### Superhero +### [Resources](resources/index.md) -[Superhero](superhero/index.md) -Create impactful hero banners with images, headings, and call-to-action buttons. Choose from 8 variants: +Resource links displayed on right sidebar. -**Layout Variants:** -- [Default](superhero/superhero-default.md) - Standard layout for documentation pages -- [Half Width](superhero/superhero-halfwidth.md) - Split-screen layout for product pages -- [Centered](superhero/superhero-centered.md) - Centered layout for home pages -- [Centered XL](superhero/superhero-centeredxl.md) - Extra-large centered layout +### [Superhero](superhero/index.md) -**Enhanced Variants:** -- [Default with Background](superhero/superhero-default-with-background-image.md) - With custom background color -- [Default with Gradient](superhero/superhero-default-with-background-image-and-color.md) - With gradient background -- [Half Width with Background](superhero/superhero-halfwidth-with-background-image.md) - With full-width background -- [Half Width with Video](superhero/superhero-halfwidth-with-background-image-and-video.md) - With video content +Hero banners with images and CTAs. 8 variants: -### Tab +**Layouts:** +- [Default](superhero/superhero-default.md) - Standard +- [Half Width](superhero/superhero-halfwidth.md) - Split-screen +- [Centered](superhero/superhero-centered.md) - Center-aligned +- [Centered XL](superhero/superhero-centeredxl.md) - Extra-large -[Tab](tab/index.md) -Tabbed content for organizing related information. +**Enhanced:** +- [Default + Background](superhero/superhero-default-with-background-image.md) - Custom background +- [Default + Gradient](superhero/superhero-default-with-background-image-and-color.md) - Gradient background +- [Half Width + Background](superhero/superhero-halfwidth-with-background-image.md) - Full-width background +- [Half Width + Video](superhero/superhero-halfwidth-with-background-image-and-video.md) - Video background -## Getting Started +### [Tab](tab/index.md) -1. Choose your hero block variant based on page type -2. Configure navigation in `config.md` -3. Use content blocks to build your page -4. Add code examples with appropriate formatting -5. Include alerts and announcements as needed +Organize content in tabs. diff --git a/src/pages/blocks/inline-alert/index.md b/src/pages/blocks/inline-alert/index.md index f63a4b7..e0e6d7b 100644 --- a/src/pages/blocks/inline-alert/index.md +++ b/src/pages/blocks/inline-alert/index.md @@ -5,7 +5,7 @@ description: Display inline alert messages for warnings, tips, and notes using t # Inline Alert -Display contextual alert messages to highlight important information, warnings, tips, or errors. +Alert messages for important information. ## Syntax @@ -17,74 +17,40 @@ Your alert message here. ## Parameters -- **slots**: Content structure - - `"text"`: Simple alert with text only - - `"header, text1, text2, ..."`: Alert with header and multiple text sections +- **slots**: + - `"text"` - Simple text + - `"header, text1, text2"` - With header and sections - **variant**: Alert type (default: `info`) - - `"info"`: Information (blue) - default - - `"help"`: Help or tips (purple) - - `"warning"`: Warning messages (orange) - - `"error"`: Error messages (red) - - `"success"`: Success messages (green) - - `"neutral"`: Neutral messages (gray) + - `"info"` - Blue + - `"help"` - Purple + - `"warning"` - Orange + - `"error"` - Red + - `"success"` - Green + - `"neutral"` - Gray ## Examples -### Info Alert (Default) +### Info (Default) -This is the text that displays within the default alert variant — info. +This is an info alert. -### Help Alert - - - -### Alternative steps: - -**Step 1:** This is faux step text for the `text1` slot. -This is faux step text for the `text1` slot. -This is faux step text for the `text1` slot. -This is faux step text for the `text1` slot. -This is faux step text for the `text1` slot. - -**Step 2:** This is faux step text for the `text2` slot. -This is faux step text for the `text2` slot. -This is faux step text for the `text2` slot. - -**Step 3:** This is faux step text for the `text3` slot. - -**Step 4:** This is faux step text for the `text4` slot. -This is faux step text for the `text3` slot. - -### Warning Alert +### Warning -This is an inline alert warning. +This is a warning alert. -### Error Alert +### Error -This is an inline alert error. +This is an error alert. -### Success Alert +### Success -This is an inline alert success. - -### Neutral Alert - - - -This is an inline alert neutral. - -## Best Practices - -- Choose the right variant for your message type -- Keep messages concise and actionable -- Don't overuse alerts - they lose impact -- Place alerts near relevant content +This is a success alert. diff --git a/src/pages/blocks/inline-code/index.md b/src/pages/blocks/inline-code/index.md index 2a4be22..58f2b1b 100644 --- a/src/pages/blocks/inline-code/index.md +++ b/src/pages/blocks/inline-code/index.md @@ -5,43 +5,30 @@ description: Format inline code snippets, variable names, function names, and te # Inline Code -Format code elements, variable names, and technical terms within your text using backticks. +Format code elements with backticks. ## Syntax -To create inline code, wrap text with single backticks (`` ` ``): +Wrap text with single backticks (`` ` ``): ```markdown -Use the `variableName` variable to store the value. +Use the `variableName` variable. ``` -**Result:** Use the `variableName` variable to store the value. +**Result:** Use the `variableName` variable. ## Common Uses -- Variable names: `count`, `userId`, `isEnabled` -- Function names: `getUserData()`, `calculateTotal()` -- Class names: `UserManager`, `Color` -- File names: `config.json`, `index.md` +- Variables: `count`, `userId` +- Functions: `getUserData()`, `calculateTotal()` +- Classes: `UserManager`, `Color` +- Files: `config.json`, `index.md` - Commands: `-v`, `--help` -## Linking Inline Code - -You can combine inline code with links to reference API documentation: +## With Links ```markdown -Use the [`Color`](https://example.com/api/Color) class to define colors. +Use the [`Color`](https://example.com/api/Color) class. ``` -**Result:** Use the [`Color`](https://example.com/api/Color) class to define colors. - -## Example - -Colors in the API are created as instances of the [`Color`](https://example.com/api/Color) class: objects with `red`, `green`, `blue`, and `alpha` (optional) values in the range from 0 to 1. The `alpha` value represents the opacity of the color, with 0 being fully transparent and 1 fully opaque. - -## Best Practices - -- Use inline code for technical terms and code elements only -- Don't overuse it for emphasis -- For multi-line code, use code blocks instead -- Be consistent throughout your documentation \ No newline at end of file +**Result:** Use the [`Color`](https://example.com/api/Color) class. \ No newline at end of file diff --git a/src/pages/blocks/links/index.md b/src/pages/blocks/links/index.md index 1ba8062..bec01ff 100644 --- a/src/pages/blocks/links/index.md +++ b/src/pages/blocks/links/index.md @@ -5,11 +5,7 @@ description: Learn how to create links between documentation pages using relativ # Links -Create links between documentation pages using standard markdown link syntax with relative or absolute paths. - -## How Links Work - -All links are resolved relative to the `src/pages/` directory. You can use either relative paths (from your current location) or absolute paths (from the root). +Link between pages using relative or absolute paths. ## Syntax @@ -19,98 +15,27 @@ All links are resolved relative to the `src/pages/` directory. You can use eithe ## Path Types -### Relative Paths - -Relative paths are based on your current page location. - -**Example:** If you're on `src/pages/blocks/links/index.md` and want to link to `src/pages/blocks/column/index.md`: - +**Relative**: Based on current page location ```markdown -[Column Block](../column/index.md) +[Column Block](../column/index.md) # Go up one level +[Tab Block](column/index.md) # Same directory ``` -- `..` moves up one directory level (from `links/` to `blocks/`) -- Then navigates to `column/index.md` - -**Another example:** From `src/pages/blocks/index.md` to `src/pages/blocks/column/index.md`: - -```markdown -[Column Block](column/index.md) -``` - -### Absolute Paths - -Absolute paths start from the `src/pages/` directory with a leading `/`. - -**Example:** From any page to `src/pages/blocks/column/index.md`: - +**Absolute**: Start from `src/pages/` with `/` ```markdown [Column Block](/blocks/column/index.md) ``` -The leading `/` indicates the path starts from `src/pages/`. - -## Examples - -### Linking Within the Same Directory - -If you're in `src/pages/blocks/` and want to link to another file in the same directory: - -```markdown -[Accordion](accordion/index.md) -[Tab Block](tab/index.md) -``` - -### Linking to Parent Directory - -From `src/pages/blocks/column/index.md` to `src/pages/blocks/index.md`: +## Path Resolution -```markdown -[Back to Blocks](../index.md) -``` - -### Linking Across Directories - -From `src/pages/blocks/column/index.md` to `src/pages/blocks/superhero/index.md`: - -```markdown -[Superhero Block](../superhero/index.md) -``` - -### Using Absolute Paths - -From anywhere in the documentation: - -```markdown -[Column Block](/blocks/column/index.md) -[Home Page](/index.md) -[Configuration](/config.md) -``` - -## Path Resolution Table - -| Current Page Location | Target Page | Relative Path | Absolute Path | +| From | To | Relative | Absolute | | --- | --- | --- | --- | | `blocks/links/index.md` | `blocks/column/index.md` | `../column/index.md` | `/blocks/column/index.md` | | `blocks/index.md` | `blocks/column/index.md` | `column/index.md` | `/blocks/column/index.md` | -| `blocks/column/index.md` | `blocks/index.md` | `../index.md` | `/blocks/index.md` | | `blocks/column/index.md` | `index.md` (root) | `../../index.md` | `/index.md` | -## Best Practices - -- Use relative paths when linking between pages in the same section -- Use absolute paths when linking from deeply nested pages to other sections -- Always include the `.md` file extension -- Link to `index.md` files directly (e.g., `column/index.md` not just `column/`) -- Test your links to ensure they resolve correctly - ## External Links -For external URLs, use standard markdown syntax: - ```markdown [External Site](https://example.com) ``` - -External links will open in the same window by default. - diff --git a/src/pages/blocks/list/index.md b/src/pages/blocks/list/index.md index 6fc7753..8f800b1 100644 --- a/src/pages/blocks/list/index.md +++ b/src/pages/blocks/list/index.md @@ -5,7 +5,7 @@ description: Create styled lists with icons and various formatting options using # List Block -Create styled lists with icons and custom colors to highlight features, benefits, or key points. +Styled lists with icons. ## Syntax @@ -15,21 +15,20 @@ Create styled lists with icons and custom colors to highlight features, benefits ## Parameters -- **slots**: Content structure for each list item - - `"text1, text2"`: Two text elements per item (e.g., title and description) +- **slots**: `"text1, text2"` - Two text elements per item -- **repeat**: Number of list items to display +- **repeat**: Number of items -- **icon**: Icon type to display (optional) - - `"checkmark"`: Checkmark icon - - Other icon options available +- **icon**: Icon type (optional) + - `"checkmark"` - Checkmark + - Other options available -- **iconColor**: Hex color for the icon (default: theme color) - - Example: `"#2ac3a2"`, `"#ff0000"` +- **iconColor**: Hex color (optional) + - Example: `"#2ac3a2"` -- **variant**: Layout variant (optional) - - `"fullWidth"`: Full-width layout - - Default: Standard layout +- **variant**: Layout (optional) + - `"fullWidth"` - Full-width + - Default: Standard ## Example @@ -50,10 +49,3 @@ No credit card required Scalable for enterprise needs Built for high performance - -## Best Practices - -- Keep text concise and scannable -- Limit to 4-8 items for readability -- Use consistent icon colors -- Use checkmarks for positive features diff --git a/src/pages/blocks/onthispage/index.md b/src/pages/blocks/onthispage/index.md index a7b42cc..a69722c 100644 --- a/src/pages/blocks/onthispage/index.md +++ b/src/pages/blocks/onthispage/index.md @@ -5,25 +5,15 @@ description: Automatic table of contents sidebar that displays H2 and H3 heading # On This Page -Automatically generated table of contents that appears on the right side of pages for quick navigation to different sections. +Auto-generated table of contents from H2 and H3 headings. ## How It Works -The component is **automatically generated** from your page headings. No configuration required. +**Automatically generated** - no configuration needed. -- Scans your markdown for H2 (`##`) and H3 (`###`) headings -- Creates anchor links for each heading -- Displays them in a sidebar on the right -- Updates the active link as users scroll - -## Example +- Scans H2 (`##`) and H3 (`###`) headings +- Creates clickable anchor links +- Displays in right sidebar +- Updates as you scroll ![onthispage](../../assets/onthispage.png) - -## Best Practices - -- Use descriptive, concise headings -- Maintain clear H2 and H3 hierarchy -- Avoid very long heading text -- Keep nesting to H2 and H3 only - diff --git a/src/pages/blocks/redoclyapiblock/redocly-api-block-configs.md b/src/pages/blocks/redoclyapiblock/redocly-api-block-configs.md index 92acb0b..76dcb80 100644 --- a/src/pages/blocks/redoclyapiblock/redocly-api-block-configs.md +++ b/src/pages/blocks/redoclyapiblock/redocly-api-block-configs.md @@ -54,7 +54,7 @@ When no options are specified, the component uses these defaults: - -## Best Practices - -- Start with default settings and customize as needed -- Use typography to match your brand -- Consider disabling sidebar for simpler APIs -- Test code sample languages with your audience diff --git a/src/pages/blocks/redoclyapiblock/redocly-api-block-default.md b/src/pages/blocks/redoclyapiblock/redocly-api-block-default.md index cde50d0..a335745 100644 --- a/src/pages/blocks/redoclyapiblock/redocly-api-block-default.md +++ b/src/pages/blocks/redoclyapiblock/redocly-api-block-default.md @@ -28,10 +28,3 @@ Display interactive API documentation from OpenAPI specification files. ## Example - -## Best Practices - -- Use valid OpenAPI 3.0+ specification files -- Keep your spec well-organized with clear descriptions -- Provide examples in your specification -- Use relative paths for local files diff --git a/src/pages/blocks/redoclyapiblock/redocly-api-block-no-layout.md b/src/pages/blocks/redoclyapiblock/redocly-api-block-no-layout.md index 368ba39..ff37dfa 100644 --- a/src/pages/blocks/redoclyapiblock/redocly-api-block-no-layout.md +++ b/src/pages/blocks/redoclyapiblock/redocly-api-block-no-layout.md @@ -37,13 +37,6 @@ layout: none -## Best Practices - -- Use for dedicated API reference pages -- Set scrollYOffset when you have fixed headers -- Consider removing navigation elements for cleaner focus -- Test on different screen sizes for responsive design - ## Related - [Redocly API Block Default](/blocks/redoclyapiblock/redocly-api-block-default.md) - With standard layout diff --git a/src/pages/blocks/redoclyapiblock/redocly-api-block-no-sidebar-no-search.md b/src/pages/blocks/redoclyapiblock/redocly-api-block-no-sidebar-no-search.md index 1bd6fb8..c7f58ab 100644 --- a/src/pages/blocks/redoclyapiblock/redocly-api-block-no-sidebar-no-search.md +++ b/src/pages/blocks/redoclyapiblock/redocly-api-block-no-sidebar-no-search.md @@ -30,10 +30,3 @@ By default, both sidebar and search are enabled (`disableSidebar: false`, `disab ## Example - -## Best Practices - -- Use only for very simple APIs -- Ensure content is logically organized for linear reading -- Consider alternative navigation methods if needed -- Good for documentation that will be read sequentially diff --git a/src/pages/blocks/redoclyapiblock/redocly-api-block-no-sidebar.md b/src/pages/blocks/redoclyapiblock/redocly-api-block-no-sidebar.md index 249e9bc..4d72642 100644 --- a/src/pages/blocks/redoclyapiblock/redocly-api-block-no-sidebar.md +++ b/src/pages/blocks/redoclyapiblock/redocly-api-block-no-sidebar.md @@ -29,10 +29,3 @@ By default, the Redocly API Block shows a left sidebar with navigation (`disable ## Example - -## Best Practices - -- Use for APIs with limited endpoints -- Combine with search disabled for even cleaner layout -- Consider if users need quick navigation between endpoints -- Good for sequential documentation reading diff --git a/src/pages/blocks/redoclyapiblock/redocly-api-block-no-y-scroll-offset.md b/src/pages/blocks/redoclyapiblock/redocly-api-block-no-y-scroll-offset.md index 167179d..34c6d1b 100644 --- a/src/pages/blocks/redoclyapiblock/redocly-api-block-no-y-scroll-offset.md +++ b/src/pages/blocks/redoclyapiblock/redocly-api-block-no-y-scroll-offset.md @@ -31,10 +31,3 @@ Without this offset, anchor links might scroll content underneath fixed elements ## Example - -## Best Practices - -- Set scrollYOffset to match your fixed header height -- Common values: 64px (standard header), 80px (larger header) -- Test anchor navigation to ensure proper scrolling -- Update if you change your header height diff --git a/src/pages/blocks/redoclyapiblock/redocly-overflow.md b/src/pages/blocks/redoclyapiblock/redocly-overflow.md index a6425f0..618d32d 100644 --- a/src/pages/blocks/redoclyapiblock/redocly-overflow.md +++ b/src/pages/blocks/redoclyapiblock/redocly-overflow.md @@ -38,12 +38,4 @@ You can also customize the typography to match your brand. The default font stac This example loads an API specification from an external registry: - - -## Best Practices - -- Use HTTPS URLs for external specifications -- Ensure external APIs have CORS enabled -- Consider caching external specs for performance -- Verify external URLs are stable and maintained -- Use custom typography to match your brand \ No newline at end of file + \ No newline at end of file diff --git a/src/pages/blocks/resources/index.md b/src/pages/blocks/resources/index.md new file mode 100644 index 0000000..659d228 --- /dev/null +++ b/src/pages/blocks/resources/index.md @@ -0,0 +1,35 @@ +--- +title: Resources Block +description: Display a resources section with useful links. +--- + +# Resources Block + +Resource links displayed on the right side of the page, above "On This Page" if present. + +## Syntax + +```markdown + + +#### Resources + +* [Quick start guide](getting-started/index.md) +* [Endpoint guides](endpoints/index.md) +* [API reference](https://example.com/api-reference) +* [GitHub repository](https://github.com/example/repo) +``` + +## Parameters + +- **slots**: `"heading, links"` - Heading and links + + + +#### Resources + +* [Quick start guide](getting-started/index.md) +* [Endpoint guides](endpoints/index.md) +* [API reference](https://example.com/api-reference) +* [GitHub repository](https://github.com/example/repo) + diff --git a/src/pages/blocks/resources/resources-with-no-hero.md b/src/pages/blocks/resources/resources-with-no-hero.md deleted file mode 100644 index 1ab6414..0000000 --- a/src/pages/blocks/resources/resources-with-no-hero.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Resources Block without Hero -description: Display a resources section with useful links without a hero banner for a simpler layout. ---- - -# Resources Block without Hero - -Display a clean resources section with links to documentation and references. - -## Syntax - -```markdown - - -#### Resources - -* [Link 1](url) -* [Link 2](url) -``` - -## Parameters - -- **slots**: Define content structure - - `"heading, links"`: Heading and list of links - - - -#### Resources - -* [Quick start guide](getting-started/index.md) -* [Endpoint guides](endpoints/index.md) -* [API reference](https://example.com/api-reference) -* [GitHub repository](https://github.com/example/repo) - -## Best Practices - -- Use descriptive headings for resource sections -- Keep link text clear and action-oriented -- Order links by importance diff --git a/src/pages/blocks/resources/resources.md b/src/pages/blocks/resources/resources.md deleted file mode 100644 index 5841b47..0000000 --- a/src/pages/blocks/resources/resources.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Resources Block with Hero -description: Display a resources section with links alongside a hero banner for an engaging landing page. ---- - -# Resources Block with Hero - -Combine a hero banner with a resources section to display key documentation links. - -## Syntax - -### Resources Component - -```markdown - -``` - - - -![Hero image](../../../assets/hero.png) - -# Developer Platform API - -Build powerful applications with our comprehensive API platform and services. - -* [Get Started](https://example.com/getting-started) - - - -#### Resources - -* [Quick start guide](getting-started/index.md) -* [Endpoint guides](endpoints/index.md) -* [API reference](https://example.com/api-reference) -* [GitHub repository](https://github.com/example/repo) - -## Best Practices - -- Keep resource links concise and clearly labeled -- Link to the most important resources first -- Use hero to introduce the product or API - diff --git a/src/pages/blocks/sidenav/index.md b/src/pages/blocks/sidenav/index.md index ec14e67..ceda9b5 100644 --- a/src/pages/blocks/sidenav/index.md +++ b/src/pages/blocks/sidenav/index.md @@ -5,68 +5,39 @@ description: Learn how to configure sidebar navigation using subPages in config. # Side Navigation -Side Navigation (sidebar) is configured in the `config.md` file using the `subPages` section. It creates a hierarchical navigation menu that appears on the left side of your documentation pages. +Configure sidebar navigation in `config.md` using `subPages`. -## Configuration Example +## Example -```yaml +```md - subPages: - - [Overview](blocks/index.md) + - [Content Blocks](/blocks/index.md) - [Accordion](/blocks/accordion/index.md) - [Accordion Basic](/blocks/accordion/accordion-basic.md) - [Accordion with Table & Code](/blocks/accordion/accordion-with-table-and-code.md) - - [Announcement](/blocks/announcement/index.md) - - [Announcement Button only](/blocks/announcement/announcement-button-only.md) - - [Announcement With Heading](/blocks/announcement/announcement-with-heading.md) - - [Edition](/blocks/edition/index.md) - - [Edition without Link](/blocks/edition/edition-with-no-link.md) - - [Edition with Link](/blocks/edition/edition-with-link.md) ``` -## How It Works +## Format -The `subPages` array creates a hierarchical sidebar menu with multiple nesting levels. +`[Display Text](path/to/file.md)` -**Hierarchy:** -- No indentation = Top-level section -- 2 spaces indentation = Subsection -- 4 spaces indentation = Nested page - -**Format:** `[Display Text](relative/path.md)` - -- `[Accordion]` - The text displayed in the sidebar -- `(/blocks/accordion/index.md)` - The relative path to the page under `src/pages/` - -Paths can start with or without `/` - both resolve relative to `src/pages/`. - -**Example:** -- `[Accordion](/blocks/accordion/index.md)` displays "Accordion" and links to `src/pages/blocks/accordion/index.md` - -## Visual Result +**Indentation = Nesting:** +```md +- [Overview](blocks/index.md) # Top level + - [Accordion](/blocks/accordion/index.md) # Nested (2 spaces) + - [Basic](/blocks/accordion/basic.md) # Nested deeper (4 spaces) +``` -The above configuration creates this sidebar structure: +## Result ![sidenav image](../../assets/sidenav.png) -## Path Resolution - -All paths are relative to `src/pages/` and work with the `pathPrefix` setting: - -| Config Path | Actual File Location | Full URL (with pathPrefix) | -| --- | --- | --- | -| `blocks/index.md` | `src/pages/blocks/index.md` | `/dev-docs-reference/blocks/` | -| `/blocks/accordion/index.md` | `src/pages/blocks/accordion/index.md` | `/dev-docs-reference/blocks/accordion/` | -| `/blocks/accordion/accordion-basic.md` | `src/pages/blocks/accordion/accordion-basic.md` | `/dev-docs-reference/blocks/accordion/accordion-basic` | +## Paths -## Best Practices +All paths in `config.md` are relative to `/src/pages/`. External links require full paths (e.g., `https://example.com`). -- Keep nesting levels to 2-3 maximum for better user experience -- Ensure indentation is consistent (2 spaces per level) -- All paths must point to existing files under `src/pages/` -- Organize sidebar navigation to match your file structure -- Use clear, descriptive labels for each section ## Related -For configuring top navigation, see the [TopNav](/blocks/topnav/index.md) documentation. +[TopNav](/blocks/topnav/index.md) - Configure top navigation diff --git a/src/pages/blocks/site-wide-banner/index.md b/src/pages/blocks/site-wide-banner/index.md new file mode 100644 index 0000000..3dfc523 --- /dev/null +++ b/src/pages/blocks/site-wide-banner/index.md @@ -0,0 +1,50 @@ +--- +title: Site-Wide Banner +description: Learn how to add a site-wide banner that appears across all pages using site-wide-banner.json. +--- + +# Site-Wide Banner + +Display an announcement banner across all pages of your site. + +## Setup + +Create a `site-wide-banner.json` file in your root directory under /src/pages/ with the following structure: + +```json +{ + "total": 1, + "offset": 0, + "limit": 1, + "data": [ + { + "bgColor": "success", + "icon": "info", + "text": [ + "Your announcement message here." + ], + "button": "Learn More", + "buttonLink": "https://example.com", + "isClose": true + } + ], + ":type": "sheet" +} +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| `bgColor` | string | `notice` (yellow), `info` (blue), `warning` (orange), `success` (green), `neutral` (dark gray), `light` (white) | +| `icon` | string | Icon to display: `info`, `warning`, `success` | +| `text` | array | Message text (supports multiple lines) | +| `button` | string | Button text | +| `buttonLink` | string | Button URL | +| `isClose` | boolean | Allow users to dismiss the banner | + +## Example + +This is what it looks like visually. + +![sitewidebanner](../../ßassets/sitewidebanner.png) diff --git a/src/pages/blocks/superhero/index.md b/src/pages/blocks/superhero/index.md index 66b05fb..f75ed33 100644 --- a/src/pages/blocks/superhero/index.md +++ b/src/pages/blocks/superhero/index.md @@ -5,32 +5,19 @@ description: Create impactful hero banners with images, headings, text, and call # Superhero Block -Create prominent hero banners at the top of pages with images, headings, text, and call-to-action buttons. - -**Note:** Use only one hero block per page. - -## Available Variants - -There are 4 different variants to choose from: - -- **[Default](superhero-default.md)**: Standard variant for documentation pages -- **[Half Width](superhero-halfwidth.md)**: Split layout for product/platform pages -- **[Centered](superhero-centered.md)**: Centered layout for index home pages -- **[Centered XL](superhero-centeredxl.md)**: Large centered layout for impact +Hero banners at the top of pages. Use only one per page. ## Parameters -- **slots**: Content structure - - `"heading, text"`: Heading and text only - - `"image, heading, text, buttons"`: All elements +- **variant**: + - `default` - [Standard layout](superhero-default.md) + - `halfWidth` - [Split layout](superhero-halfwidth.md) + - `centered` - [Centered layout](superhero-centered.md) + - `centeredXL` - [Large centered](superhero-centeredxl.md) -- **background**: Background color (default: `rgb(29, 125, 238)`) -- **textColor**: Text color (default: `white`) -- **variant**: Layout variant (`default`, `halfWidth`, `centered`, `centeredXL`) - -## Best Practices +- **slots**: + - `"heading, text"` - Text only + - `"image, heading, text, buttons"` - All elements -- Choose the variant that matches your page type -- Keep heading text concise -- Limit call-to-action buttons to 1-2 -- Ensure good contrast between text and background \ No newline at end of file +- **background**: Background color (default: `rgb(29, 125, 238)`) +- **textColor**: Text color (default: `white`) \ No newline at end of file diff --git a/src/pages/blocks/superhero/superhero-centered.md b/src/pages/blocks/superhero/superhero-centered.md index f2ae20a..f8acfd0 100644 --- a/src/pages/blocks/superhero/superhero-centered.md +++ b/src/pages/blocks/superhero/superhero-centered.md @@ -5,47 +5,29 @@ description: Centered superhero layout with image and buttons for index home pag # Superhero - Centered Variant -The centered variant creates a visually balanced hero banner with centered content, perfect for high-impact landing pages and home pages. - -## Overview - -This variant is best suited for: -- Index home pages -- Marketing landing pages -- Product showcases -- Main portal pages +Centered hero banner with balanced layout. ## Syntax ```markdown -![Hero image](path/to/image.png) +![Hero image](../../assets/hero.png) -## Your Heading +## Build Amazing Digital Experiences -Your text here +Unleash your developer creativity with our powerful platform and tools -* [Button 1](url) -* [Button 2](url) +* [Explore our APIs](https://example.com/api) +* [Get Started](https://example.com/getting-started) ``` ## Parameters -- **variant**: Set to `"centered"` for centered layout - -- **slots**: Content structure - - `"heading"` (required): Main heading - - `"text"` (required): Descriptive text - - `"image"` (optional): Hero image - - `"buttons"` (optional): Call-to-action buttons - -- **background**: Custom background color (default: `rgb(29, 125, 238)`) - -- **textColor**: Text color (default: white) - - Options: `white`, `black`, `navy`, `gray` - -## Example +- **variant**: `"centered"` +- **slots**: `"image, heading, text, buttons"` +- **background**: Background color (default: `rgb(29, 125, 238)`) +- **textColor**: Text color (default: `white`) @@ -57,11 +39,3 @@ Unleash your developer creativity with our powerful platform and tools * [Explore our APIs](https://example.com/api) * [Get Started](https://example.com/getting-started) - -## Best Practices - -- Use high-quality, impactful hero images -- Keep text centered and concise -- Limit to 2 call-to-action buttons maximum -- Ensure image works well with text overlay -- Use for high-level, strategic pages \ No newline at end of file diff --git a/src/pages/blocks/superhero/superhero-centeredxl.md b/src/pages/blocks/superhero/superhero-centeredxl.md index 71de6ce..a26e86b 100644 --- a/src/pages/blocks/superhero/superhero-centeredxl.md +++ b/src/pages/blocks/superhero/superhero-centeredxl.md @@ -5,47 +5,29 @@ description: Extra-large centered superhero layout for maximum visual impact on # Superhero - Centered XL Variant -The centered XL variant creates an extra-large, visually dominant hero banner with centered content for maximum impact on landing pages. - -## Overview - -This variant is best suited for: -- Main portal home pages -- High-impact marketing pages -- Brand showcases -- Major product launches +Extra-large centered hero banner for maximum impact. ## Syntax ```markdown -![Hero image](path/to/image.png) +![Hero banner](../../assets/hero.png) -# Your Heading +# Build Amazing Digital Experiences -Your text here +Unleash your developer creativity with our powerful platform and tools -* [Button 1](url) -* [Button 2](url) +* [Explore our APIs](https://example.com/api) +* [Get Started](https://example.com/getting-started) ``` ## Parameters -- **variant**: Set to `"centeredXL"` for extra-large centered layout - -- **slots**: Content structure - - `"heading"` (required): Main heading - - `"text"` (required): Descriptive text - - `"image"` (optional): Hero image - - `"buttons"` (optional): Call-to-action buttons - -- **background**: Custom background color (default: `rgb(29, 125, 238)`) - -- **textColor**: Text color (default: white) - - Options: `white`, `black`, `navy`, `gray` - -## Example +- **variant**: `"centeredXL"` +- **slots**: `"image, heading, text, buttons"` +- **background**: Background color (default: `rgb(29, 125, 238)`) +- **textColor**: Text color (default: `white`) @@ -57,12 +39,3 @@ Unleash your developer creativity with our powerful platform and tools * [Explore our APIs](https://example.com/api) * [Get Started](https://example.com/getting-started) - -## Best Practices - -- Reserve for most important pages only -- Use compelling, high-resolution images -- Keep messaging bold and concise -- Ensure typography scales well at large sizes -- Test on various screen sizes for responsiveness - diff --git a/src/pages/blocks/superhero/superhero-default-with-background-image-and-color.md b/src/pages/blocks/superhero/superhero-default-with-background-image-and-color.md index bc2d189..71b73f2 100644 --- a/src/pages/blocks/superhero/superhero-default-with-background-image-and-color.md +++ b/src/pages/blocks/superhero/superhero-default-with-background-image-and-color.md @@ -5,47 +5,28 @@ description: Standard superhero layout with gradient background for modern visua # Superhero - Default with Gradient Background -The default variant with a gradient background creates a modern, visually appealing hero with smooth color transitions. - -## Overview - -This variant is best suited for: -- Modern product pages -- Creative applications -- Brand-focused landing pages -- Pages needing visual flair +Standard layout with gradient background. ## Syntax ```markdown -![Hero image](path/to/image.png) +![Hero image](../../assets/wide-SDK-Banner-570x400.png) -# Your Heading +# Developer Platform API -Your descriptive text here. +Build powerful applications with our comprehensive API platform and services. -* [Button](url) +* [Get Started](https://example.com/getting-started) ``` ## Parameters -- **slots**: Content structure - - `"image"`: Hero image - - `"heading"` (required): Main heading - - `"text"` (required): Descriptive text - - `"buttons"` (optional): Call-to-action buttons +- **slots**: `"image, heading, text, buttons"` +- **background**: `linear-gradient(angle, color1, color2)` +- **textColor**: Text color (default: `white`) -- **background**: CSS gradient - - Format: `linear-gradient(angle, color1, color2)` - - Example: `background="linear-gradient(180deg, #c946eb, #6372f5)"` - - Supports multiple color stops - -- **textColor**: Text color (default: white) - - Options: `white`, `black`, `navy`, `gray` - -## Example @@ -56,19 +37,3 @@ Your descriptive text here. Build powerful applications with our comprehensive API platform and services. * [Get Started](https://example.com/getting-started) - -## Gradient Tips - -- Use 2-3 colors for smooth transitions -- Start with brand colors -- Consider accessibility and text readability -- Test gradients at different angles (90deg, 180deg, 45deg) -- Common format: `linear-gradient(180deg, #color1, #color2)` - -## Best Practices - -- Choose gradient colors that align with brand -- Ensure text has sufficient contrast throughout gradient -- Test on multiple screen sizes -- Avoid overly busy or distracting gradients -- Use subtle gradients for professional look diff --git a/src/pages/blocks/superhero/superhero-default-with-background-image.md b/src/pages/blocks/superhero/superhero-default-with-background-image.md index 44d8e6a..88d8d51 100644 --- a/src/pages/blocks/superhero/superhero-default-with-background-image.md +++ b/src/pages/blocks/superhero/superhero-default-with-background-image.md @@ -5,46 +5,28 @@ description: Standard superhero layout with custom background image for visual i # Superhero - Default with Background Image -The default variant with a background image combines standard layout with visual interest through a custom background. - -## Overview - -This variant is best suited for: -- Documentation pages with branding -- Product pages with thematic backgrounds -- Landing pages with visual context -- Pages requiring visual hierarchy +Standard layout with custom background color. ## Syntax ```markdown -![Hero image](path/to/image.png) +![Hero image](../../assets/hero.png) -# Your Heading +# Developer Platform API -Your descriptive text here. +Build powerful applications with our comprehensive API platform and services. -* [Button](url) +* [Get Started](https://example.com/getting-started) ``` ## Parameters -- **slots**: Content structure - - `"image"`: Hero image - - `"heading"` (required): Main heading - - `"text"` (required): Descriptive text - - `"buttons"` (optional): Call-to-action buttons - -- **background**: Custom background color - - Format: `rgb(r, g, b)` or hex color - - Example: `background="rgb(22, 49, 42)"` - -- **textColor**: Text color (default: white) - - Options: `white`, `black`, `navy`, `gray` +- **slots**: `"image, heading, text, buttons"` +- **background**: `rgb(r, g, b)` or hex color +- **textColor**: Text color (default: `white`) -## Example @@ -55,10 +37,3 @@ Your descriptive text here. Build powerful applications with our comprehensive API platform and services. * [Get Started](https://example.com/getting-started) - -## Best Practices - -- Choose background colors that complement your brand -- Ensure sufficient contrast between text and background -- Use images that work well with the background -- Test readability on different screen sizes diff --git a/src/pages/blocks/superhero/superhero-default.md b/src/pages/blocks/superhero/superhero-default.md index 8f24b41..ea4248c 100644 --- a/src/pages/blocks/superhero/superhero-default.md +++ b/src/pages/blocks/superhero/superhero-default.md @@ -5,51 +5,27 @@ description: Standard superhero layout for documentation pages with heading and # Superhero - Default Variant -The default superhero variant provides a standard hero banner layout ideal for documentation pages and product introductions. - -## Overview - -This variant is best suited for: -- Documentation home pages -- API landing pages -- Product introductions -- Getting started pages +Standard hero banner layout. ## Syntax ```markdown -# Your Heading +# Developer Platform API + +Build powerful applications with our comprehensive API platform and services. -Your descriptive text here. ``` ## Parameters -- **slots**: Content structure - - `"heading"` (required): Main heading - - `"text"` (required): Descriptive text - - `"image"` (optional): Hero image - - `"buttons"` (optional): Call-to-action buttons - -- **background**: Custom background color (default: `rgb(29, 125, 238)`) - - Example: `background="rgb(22, 49, 42)"` - -- **textColor**: Text color (default: white) - - Options: `white`, `black`, `navy`, `gray` - -## Example +- **slots**: `"heading, text"` or `"image, heading, text, buttons"` +- **background**: Background color (default: `rgb(29, 125, 238)`) +- **textColor**: Text color (default: `white`) # Developer Platform API Build powerful applications with our comprehensive API platform and services. - -## Best Practices - -- Keep heading clear and focused (5-10 words) -- Use descriptive text to expand on the heading (1-2 sentences) -- Choose background colors that align with your brand -- Ensure text color has sufficient contrast with background \ No newline at end of file diff --git a/src/pages/blocks/superhero/superhero-halfwidth-with-background-image-and-video.md b/src/pages/blocks/superhero/superhero-halfwidth-with-background-image-and-video.md index 2234b85..523a33f 100644 --- a/src/pages/blocks/superhero/superhero-halfwidth-with-background-image-and-video.md +++ b/src/pages/blocks/superhero/superhero-halfwidth-with-background-image-and-video.md @@ -5,49 +5,32 @@ description: Split-screen superhero with full-width background image and video c # Superhero - Half Width with Background and Video -The half width variant with background image and video creates a dynamic, engaging hero with a background image and video content. - -## Overview - -This variant is best suited for: -- Product demonstrations -- Feature showcases with motion -- Interactive application previews -- Dynamic marketing pages +Split layout with background image and video. ## Syntax ```markdown -![Background image](path/to/background.png) +![Gradient background](../../assets/vertical-gradient.png) -[video_url](https://video-url.mp4) +[video_url](https://example.com/demo-video.mp4) -# Your Heading +# Build Extensions for Your Users -Your text here +Create powerful tools and integrations. -* [Button 1](url) -* [Button 2](url) +* [Get Started](https://example.com/getting-started) +* [View Examples](https://example.com/examples) ``` ## Parameters -- **variant**: Set to `"halfWidth"` for split layout +- **variant**: `"halfWidth"` +- **slots**: `"fullWidthBackground, video, heading, text, buttons"` +- **textColor**: Text color (recommended: `white`) +- **overGradient**: Improves button visibility -- **slots**: Content structure - - `"fullWidthBackground"`: Background image spanning full width - - `"video"`: Video content (replaces image) - - `"heading"` (required): Main heading - - `"text"` (required): Descriptive text - - `"buttons"` (optional): Call-to-action buttons - -- **textColor**: Text color (recommended: `white` for overlay) - -- **overGradient**: Improves button visibility over background - -## Example @@ -57,22 +40,7 @@ Your text here # Build Extensions for Your Users -Create powerful tools and integrations that extend platform functionality and help users accomplish more with seamless workflows. +Create powerful tools and integrations. * [Get Started](https://example.com/getting-started) * [View Examples](https://example.com/examples) - -## Video Setup - -To add a video: -1. Upload video to Google Drive or hosting service -2. Publish the video and get the public URL -3. Add as markdown link in the `video` slot: `[video_url](https://url-to-video.mp4)` - -## Best Practices - -- Use short, engaging videos (15-30 seconds) -- Ensure video works on mobile devices -- Optimize video file size for fast loading -- Consider autoplay behavior and user experience -- Provide fallback for users who prefer reduced motion \ No newline at end of file diff --git a/src/pages/blocks/superhero/superhero-halfwidth-with-background-image.md b/src/pages/blocks/superhero/superhero-halfwidth-with-background-image.md index 36f887b..efdca83 100644 --- a/src/pages/blocks/superhero/superhero-halfwidth-with-background-image.md +++ b/src/pages/blocks/superhero/superhero-halfwidth-with-background-image.md @@ -5,49 +5,32 @@ description: Split-screen superhero with full-width background image and foregro # Superhero - Half Width with Background Image -The half width variant with background image creates a layered visual effect with a full-width background and split-screen content. - -## Overview - -This variant is best suited for: -- Premium product pages -- Brand-focused landing pages -- Creative showcases -- Applications with strong visual identity +Split layout with full-width background image. ## Syntax ```markdown -![Background image](path/to/background.png) +![Gradient background](../../assets/vertical-gradient.png) -![Foreground image](path/to/image.png) +![Platform illustration](../../assets/cc-hero.png) -# Your Heading +# Build Extensions for Your Users -Your text here +Create powerful tools and integrations that extend platform functionality and help users accomplish more with seamless workflows. -* [Button 1](url) -* [Button 2](url) +* [Get Started](https://example.com/getting-started) +* [View Examples](https://example.com/examples) ``` ## Parameters -- **variant**: Set to `"halfWidth"` for split layout - -- **slots**: Content structure - - `"fullWidthBackground"`: Background image spanning full width - - `"image"`: Foreground content image - - `"heading"` (required): Main heading - - `"text"` (required): Descriptive text - - `"buttons"` (optional): Call-to-action buttons - -- **textColor**: Text color (recommended: `white` for overlay) +- **variant**: `"halfWidth"` +- **slots**: `"fullWidthBackground, image, heading, text, buttons"` +- **textColor**: Text color (recommended: `white`) +- **overGradient**: Improves button visibility -- **overGradient**: Improves button visibility over background - -## Example @@ -61,11 +44,3 @@ Create powerful tools and integrations that extend platform functionality and he * [Get Started](https://example.com/getting-started) * [View Examples](https://example.com/examples) - -## Best Practices - -- Use high-quality background images -- Ensure text is readable over background (use white text) -- Enable `overGradient` for better button contrast -- Test on various screen sizes -- Keep foreground image focused and clear diff --git a/src/pages/blocks/superhero/superhero-halfwidth.md b/src/pages/blocks/superhero/superhero-halfwidth.md index 5f5dba6..584a262 100644 --- a/src/pages/blocks/superhero/superhero-halfwidth.md +++ b/src/pages/blocks/superhero/superhero-halfwidth.md @@ -5,49 +5,30 @@ description: Split-screen superhero layout with image and content side-by-side f # Superhero - Half Width Variant -The half width variant creates a split-screen layout with an image on one side and content on the other, ideal for product and platform pages. - -## Overview - -This variant is best suited for: -- Product pages -- Platform landing pages -- Feature showcases -- Application overviews +Split-screen layout with image and content side-by-side. ## Syntax ```markdown -![Hero image](path/to/image.png) +![Hero banner](../../assets/hero.png) -# Your Heading +# Extend Your Application -Your descriptive text here. +Build powerful extensions and integrations with our developer platform. Create custom tools, automate workflows, and seamlessly integrate with existing systems using our comprehensive APIs and SDKs. -* [Button](url) +* [Get Started](https://example.com/getting-started) ``` ## Parameters -- **variant**: Set to `"halfWidth"` for split layout +- **variant**: `"halfWidth"` +- **slots**: `"image, heading, text, buttons"` +- **background**: Background color (default: `rgb(255, 255, 255)`) +- **textColor**: Text color (default: `black`) +- **overGradient**: Improves button visibility -- **slots**: Content structure - - `"heading"` (required): Main heading - - `"text"` (required): Descriptive text - - `"image"` or `"video"` (required): Visual element - - `"fullWidthBackground"` (optional): Full-width background option - - `"buttons"` (optional): Call-to-action buttons - -- **background**: Custom background color (default: `rgb(255, 255, 255)`) - -- **textColor**: Text color (default: black) - - Options: `white`, `black`, `navy`, `gray` - -- **overGradient**: Improves button visibility against gradient backgrounds - -## Example @@ -58,11 +39,3 @@ Your descriptive text here. Build powerful extensions and integrations with our developer platform. Create custom tools, automate workflows, and seamlessly integrate with existing systems using our comprehensive APIs and SDKs. * [Get Started](https://example.com/getting-started) - -## Best Practices - -- Use images that complement rather than compete with text -- Keep text concise to fit the half-width layout -- Choose images with clear focal points -- Consider using video for dynamic content -- Test layout on mobile where it stacks vertically diff --git a/src/pages/blocks/tab/index.md b/src/pages/blocks/tab/index.md index bcfb975..0381858 100644 --- a/src/pages/blocks/tab/index.md +++ b/src/pages/blocks/tab/index.md @@ -5,7 +5,7 @@ description: Organize related content using tabbed layouts with the Tab block co # Tab Block -Organize related content into tabbed sections for easy switching between different views. +Organize content in tabs. ## Syntax @@ -101,24 +101,3 @@ content tab 2 ![icon](../../assets/test-icon.png) content tab 3 - -### Simple Tabs - -Basic tabs with just headings and content: - - - -## Tab 1 - -content tab 1 - -## Tab 2 - -content tab 2 - -## Best Practices - -- Use clear, concise tab labels -- Limit to 3-7 tabs for usability -- Group related content together -- Place most important content in the first tab diff --git a/src/pages/blocks/topnav/index.md b/src/pages/blocks/topnav/index.md index b971ed4..8d84270 100644 --- a/src/pages/blocks/topnav/index.md +++ b/src/pages/blocks/topnav/index.md @@ -5,121 +5,53 @@ description: Learn how to configure top navigation in config.md for your documen # Top Navigation -Top Navigation is configured in the `config.md` file and controls how pages appear in the main navigation bar of your site. The navigation structure is based on the directory structure under `src/pages/`. +Configure top navigation in `config.md` using `pages`. -## Configuration Example +## Default Links -### Basic Navigation +The top navigation always includes these links first: +- **Adobe Developer** → `developer.adobe.com` +- **Products** → `developer.adobe.com/apis` -```yaml -- pathPrefix: - - /dev-docs-reference/ - -- pages: - - [Home](index.md) - - [Documentation](docs/index.md) - - [API Reference](api/index.md) -``` +Your custom links from `pages` appear after these default links. -### With Dropdown Menu +## Example -```yaml +```md - pathPrefix: - /dev-docs-reference/ - pages: - - [Home](index.md) + - [Overview](index.md) - [Reference Docs](blocks/index.md) - - [Version 1.0](blocks/version1.md) - - [Version 2.0](blocks/version2.md) - - [API Reference](api/index.md) + - [Version 1.0](blocks/version1.md) + - [Version 2.0](blocks/version2.md) ``` -## How It Works +Indent items to create dropdowns: -The configuration consists of two main components: +![topnav_dropdown](../../assets/topnav.png) -### pathPrefix +## Components -The `pathPrefix` is the base URL path for your content repository. This prefix is prepended to all page routes. - -```yaml +**pathPrefix**: Base URL path prepended to the domain +```md - pathPrefix: - /dev-docs-reference/ ``` -With this configuration, your pages will be accessible at: -- `/dev-docs-reference/` → Home page -- `/dev-docs-reference/docs/` → Documentation page -- `/dev-docs-reference/api/` → API Reference page - -### pages - -The `pages` array defines the top navigation items that appear in the main navigation bar. - -```yaml +**pages**: Navigation items in the top bar +```md - pages: - [Home](index.md) - [Documentation](docs/index.md) - - [API Reference](api/index.md) ``` -**Format:** `[Display Text](relative/path.md)` - -- `[Home]` - The text displayed in the navigation bar -- `(index.md)` - The relative path to the page under `src/pages/` - -### Dropdown Menus - -You can create dropdown menus in the top navigation by nesting items under a parent page: - -```yaml -- pages: - - [Home](index.md) - - [Reference Docs](blocks/index.md) - - [Version 1.0](blocks/version1.md) - - [Version 2.0](blocks/version2.md) - - [API Reference](api/index.md) -``` - -This creates a dropdown under "Reference Docs" with two options: -![topnav_dropdown](../../assets/topnav_dropdown.png) - -**Common Uses for Dropdowns:** -- Version switching (v1.0, v2.0, v3.0) -- Multiple guides under one category -- Different API versions or endpoints -- Platform-specific documentation - -**Dropdown Format:** -- Parent item: `- [Parent Label](parent-page.md)` -- Child items (indented): ` - [Child Label](child-page.md)` - -## Visual Result - -The above configuration creates a navigation bar at the top of your site with the specified items displayed horizontally. - -![Top Navigation Example](../../assets/topnav.png) - -## Path Resolution - -All paths are relative to `src/pages/`: - -| Config Path | Actual File Location | -| --- | --- | -| `index.md` | `src/pages/index.md` | -| `docs/index.md` | `src/pages/docs/index.md` | -| `api/index.md` | `src/pages/api/index.md` | +## Paths -## Best Practices +All paths in `config.md` are relative to `/src/pages/`. External links require full paths (e.g., `https://example.com`). -- Keep top navigation items to 3-5 main sections -- Use clear, concise labels for navigation items -- Use dropdowns for version switching or related sub-sections -- Limit dropdown items to 3-6 options for usability -- Ensure all paths point to existing files under `src/pages/` -- The pathPrefix should match your repository or deployment path ## Related -For configuring sidebar navigation, see the [SideNav](/blocks/sidenav/index.md) documentation. +[SideNav](/blocks/sidenav/index.md) - Configure sidebar navigation diff --git a/src/pages/config.md b/src/pages/config.md index b0a9363..cd600d7 100644 --- a/src/pages/config.md +++ b/src/pages/config.md @@ -4,7 +4,7 @@ - pages: - [Overview](index.md) - [Reference Docs](blocks/index.md) - + - subPages: - [Overview](blocks/index.md) - [Configuration Blocks](#configuration-blocks) @@ -12,13 +12,10 @@ - [TopNav](/blocks/topnav/index.md) - [Breadcrumbs](/blocks/breadcrumb/index.md) - [Footer](/blocks/footer/index.md) + - [Site-Wide Banner](/blocks/site-wide-banner/index.md) - [Content Blocks](#content-blocks) - [Accordion](/blocks/accordion/index.md) - - [Accordion Basic](/blocks/accordion/accordion-basic.md) - - [Accordion with Table & Code](/blocks/accordion/accordion-with-table-and-code.md) - [Announcement](/blocks/announcement/index.md) - - [Announcement Button only](/blocks/announcement/announcement-button-only.md) - - [Announcement With Heading](/blocks/announcement/announcement-with-heading.md) - [Code](/blocks/code/index.md) - [Code Basic](/blocks/code/code-basic.md) - [Code Highlighted Line](/blocks/code/code-highlighted-line.md) @@ -31,8 +28,6 @@ - [Column](/blocks/column/index.md) - [Discover Block](/blocks/discoverblock/index.md) - [Edition](/blocks/edition/index.md) - - [Edition without Link](/blocks/edition/edition-with-no-link.md) - - [Edition with Link](/blocks/edition/edition-with-link.md) - [HeroSimple](#herosimple) - [HeroSimple (default)](/blocks/herosimple/herosimple-default.md) - [HeroSimple fullWidth](/blocks/herosimple/herosimple-fullwidth.md) @@ -51,9 +46,7 @@ - [Redocly API Block No Sidebar No Search](blocks/redoclyapiblock/redocly-api-block-no-sidebar-no-search.md) - [Redocly API Block No Y Scroll Offset](blocks/redoclyapiblock/redocly-api-block-no-y-scroll-offset.md) - [Redocly Overflow](blocks/redoclyapiblock/redocly-overflow.md) - - [Resources](blocks/resources/resources.md) - - [Resources](blocks/resources/resources.md) - - [Resources with No Hero](blocks/resources/resources-with-no-hero.md) + - [Resources](/blocks/resources/index.md) - [Superhero](/blocks/superhero/index.md) - [Superhero Default](blocks/superhero/superhero-default.md) - [Superhero Default with Background Image](blocks/superhero/superhero-default-with-background-image.md)