Anchors

Anchors are prominent navigation elements that provide persistent access to key sections of your documentation. They appear at the top of your sidebar, above the regular navigation groups, making them perfect for highlighting important areas like API references, external resources, or main content sections.

What are Anchors?

Anchors serve as fixed navigation points that remain visible regardless of where users are in your documentation. Unlike regular navigation items that may be nested within groups, anchors provide immediate access to frequently-used resources or major sections of your documentation.

Anchors are ideal for creating shortcuts to your most important documentation sections, external resources like community forums, or separating different types of content (e.g., guides vs. API reference).

One of the most powerful features of anchors is their ability to automatically group and display different navigation sidebars based on the URL routing. When you click on an anchor with an internal URL, Docsalot intelligently displays only the navigation groups that match that anchor’s URL pattern.

Anchors with internal URLs automatically filter the navigation sidebar to show only pages that match their URL pattern. This creates distinct navigation contexts for different sections of your documentation.

How it works:

An anchor with url: "components" will display all navigation pages with URLs matching /components/*
An anchor with url: "document-apis" will display all navigation pages with URLs matching /document-apis/*
The sidebar dynamically updates based on the active anchor, showing only relevant navigation groups

Consider this configuration:

{
  "anchors": [
    {
      "name": "Documentation",
      "icon": "book-open",
      "url": "docs"
    },
    {
      "name": "Components",
      "icon": "grid-2",
      "url": "components"
    },
    {
      "name": "Document APIs",
      "icon": "square-terminal",
      "url": "document-apis"
    }
  ],
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["docs/quickstart", "docs/installation"]
    },
    {
      "group": "Guides",
      "pages": ["docs/basics", "docs/advanced"]
    },
    {
      "group": "Organization Components",
      "pages": ["components/accordions", "components/cards", "components/tabs"]
    },
    {
      "group": "Layout Components",
      "pages": ["components/steps", "components/card-group"]
    },
    {
      "group": "API Basics",
      "pages": ["document-apis/authentication", "document-apis/openapi-setup"]
    },
    {
      "group": "Endpoints",
      "pages": ["document-apis/playground", "document-apis/multiple-responses"]
    }
  ]
}

Result:

Clicking “Documentation” anchor → Sidebar shows only “Getting Started” and “Guides” groups
Clicking “Components” anchor → Sidebar shows only “Organization Components” and “Layout Components” groups
Clicking “Document APIs” anchor → Sidebar shows only “API Basics” and “Endpoints” groups

This automatic grouping creates a clean, focused navigation experience where users only see relevant content for their current context, reducing cognitive load and improving discoverability.

Configuration

Anchors are configured in the layout.json file using the anchors array. Each anchor is an object that defines its appearance and destination.

Basic Structure

{
  "anchors": [
    {
      "name": "Documentation",
      "icon": "book-open",
      "url": "docs"
    },
    {
      "name": "API Reference",
      "icon": "square-terminal",
      "url": "api-reference"
    },
    {
      "name": "Community",
      "icon": "discord",
      "url": "https://discord.gg/Dp6EpTv4BU"
    }
  ]
}

Anchor Properties

Each anchor object supports the following properties:

name

required

string

The display text shown in the sidebar. Keep it concise but descriptive.

url

required

string

The destination URL. Can be:

Internal path: Reference to a page in your docs (e.g., "api-reference", "getting-started")
External URL: Full URL to external resources (e.g., "https://discord.gg/Dp6EpTv4BU")

Internal paths should not include a leading slash. Use "docs" instead of "/docs".

icon

string

The icon displayed next to the anchor name. Uses icon names from:

Font Awesome (e.g., "book", "code", "users")
Lucide Icons (e.g., "book-open", "square-terminal", "grid-2")

Popular choices include:

"book-open" - Documentation
"square-terminal" or "code" - API Reference
"discord", "slack" - Community channels
"newspaper" - Blog or changelog
"grid-2" - Components or modules

iconType

string

The style variant of Font Awesome icons. Options include:

"brands" - Brand icons
"duotone" - Two-tone icons
"light" - Light weight icons
"regular" - Regular weight icons (default)
"sharp-solid" - Sharp corners, solid style
"solid" - Solid/filled icons
"thin" - Thin weight icons

color

string | object

Custom color for the anchor. Can be specified as:

Single color (hex string):

"color": "#8B5CF6"

Gradient (object with from and to properties):

"color": {
  "from": "#8B5CF6",
  "to": "#EC4899"
}

Top Anchor Configuration

In addition to custom anchors, Docsalot provides a default “Documentation” entry. Without tabs, it appears at the top of your sidebar. When you configure tabs, the same topAnchor becomes the default header tab that links to your documentation root.

You can customize this default entry using the topAnchor field in your layout.json.

Default Top Anchor

By default, every Docsalot documentation site includes a top anchor with:

Name: “Documentation”
Icon: “book-open”
Icon Type: “duotone”

This entry serves as the primary entry point to your documentation home.

Customizing the Top Anchor

You can override the default top anchor by adding a topAnchor object to your layout.json:

{
  "topAnchor": {
    "name": "Docs Home",
    "icon": "house",
    "iconType": "solid",
    "color": "#3B82F6"
  }
}

Top Anchor Properties

name

required

string

The display text for the top anchor. Replaces the default “Documentation” text with your custom label.

icon

string

The icon to display. Accepts any Font Awesome or Lucide icon name. Defaults to “book-open” if not specified.

iconType

string

The style variant of Font Awesome icons. Options include:

"brands" - Brand icons
"duotone" - Two-tone icons (default)
"light" - Light weight icons
"regular" - Regular weight icons
"sharp-solid" - Sharp corners, solid style
"solid" - Solid/filled icons
"thin" - Thin weight icons

color

string

Custom color for the top anchor icon and text. Accepts any valid hex color code (e.g., "#8B5CF6").

Example Configurations

{
  "topAnchor": {
    "name": "Home"
  }
}

The top anchor always links to your documentation root. Unlike regular anchors, you cannot change its destination URL - it will always navigate to your homepage. To create another major header-level destination, use tabs.

Use Cases

Use anchors to create clear divisions between different types of content. Each anchor automatically filters the sidebar to show only relevant navigation groups:

{
  "anchors": [
    {
      "name": "Guides",
      "icon": "book-open",
      "url": "guides"
    },
    {
      "name": "API Reference",
      "icon": "square-terminal",
      "url": "api-reference"
    },
    {
      "name": "Examples",
      "icon": "code",
      "url": "examples"
    }
  ],
  "navigation": [
    // These groups appear when "Guides" anchor is active
    {
      "group": "Getting Started",
      "pages": ["guides/intro", "guides/quickstart"]
    },
    {
      "group": "Advanced Guides",
      "pages": ["guides/optimization", "guides/deployment"]
    },
    // These groups appear when "API Reference" anchor is active
    {
      "group": "REST API",
      "pages": ["api-reference/endpoints", "api-reference/authentication"]
    },
    {
      "group": "GraphQL",
      "pages": ["api-reference/schema", "api-reference/queries"]
    },
    // These groups appear when "Examples" anchor is active
    {
      "group": "Basic Examples",
      "pages": ["examples/hello-world", "examples/crud-operations"]
    },
    {
      "group": "Real-World Apps",
      "pages": ["examples/blog-platform", "examples/e-commerce"]
    }
  ]
}

With this configuration:

When users click “Guides”, they see only “Getting Started” and “Advanced Guides” in the sidebar
When users click “API Reference”, they see only “REST API” and “GraphQL” in the sidebar
When users click “Examples”, they see only “Basic Examples” and “Real-World Apps” in the sidebar

2. External Resources

Link to important external resources that complement your documentation:

{
  "anchors": [
    {
      "name": "GitHub",
      "icon": "github",
      "iconType": "brands",
      "url": "https://github.com/yourusername/yourrepo"
    },
    {
      "name": "Community",
      "icon": "discord",
      "iconType": "brands",
      "url": "https://discord.gg/Dp6EpTv4BU"
    },
    {
      "name": "Status",
      "icon": "signal",
      "url": "https://status.yourcompany.com"
    }
  ]
}

3. Branded Anchors

Create visually distinct anchors using custom colors:

{
  "anchors": [
    {
      "name": "Pro Features",
      "icon": "star",
      "color": {
        "from": "#FFD700",
        "to": "#FFA500"
      },
      "url": "pro-features"
    },
    {
      "name": "Enterprise",
      "icon": "building",
      "color": "#1E3A8A",
      "url": "enterprise"
    }
  ]
}

Best Practices

Limit the Number

Keep anchors to 3-5 items maximum. Too many anchors can overwhelm users and defeat their purpose as quick-access shortcuts.

Use Clear Labels

Choose concise, descriptive names that immediately communicate the destination’s purpose. Avoid jargon or overly technical terms.

Prioritize Important Content

Reserve anchors for your most important or frequently-accessed sections. Regular navigation groups are better for detailed content organization.

Consider Visual Hierarchy

Use icons consistently and consider custom colors sparingly to maintain a professional appearance while highlighting truly special sections.

Test External Links

If linking to external resources, ensure they’re stable and regularly maintained. Broken external links in prominent positions damage user trust.

Styling Anchors

You can customize the appearance of all anchors globally through the colors.anchors property in your layout.json:

{
  "colors": {
    "anchors": {
      "from": "#1D4ED8",
      "to": "#2563EB"
    }
  }
}

This creates a consistent gradient effect across all anchors unless overridden by individual anchor color properties.

Individual anchor colors take precedence over global anchor colors, allowing you to highlight specific anchors while maintaining a consistent base style.

Examples

Here’s a comprehensive example showing how anchors work with navigation to create distinct documentation sections:

{
  "anchors": [
    {
      "name": "Documentation",
      "icon": "book-open",
      "url": "docs"
    },
    {
      "name": "Components",
      "icon": "grid-2",
      "url": "components"
    },
    {
      "name": "API Reference",
      "icon": "square-terminal",
      "color": "#059669",
      "url": "api-reference"
    },
    {
      "name": "Discord",
      "icon": "discord",
      "iconType": "brands",
      "url": "https://discord.gg/Dp6EpTv4BU"
    }
  ],
  "navigation": [
    // Documentation anchor groups (url: "docs" matches /docs/*)
    {
      "group": "Getting Started",
      "pages": [
        "docs/introduction",
        "docs/quickstart",
        "docs/installation"
      ]
    },
    {
      "group": "Core Concepts",
      "pages": [
        "docs/architecture",
        "docs/configuration",
        "docs/deployment"
      ]
    },
    // Components anchor groups (url: "components" matches /components/*)
    {
      "group": "Display Components",
      "pages": [
        "components/cards",
        "components/accordions",
        "components/callouts"
      ]
    },
    {
      "group": "Layout Components",
      "pages": [
        "components/steps",
        "components/tabs",
        "components/card-group"
      ]
    },
    // API Reference anchor groups (url: "api-reference" matches /api-reference/*)
    {
      "group": "Authentication",
      "pages": [
        "api-reference/oauth",
        "api-reference/api-keys"
      ]
    },
    {
      "group": "Endpoints",
      "pages": [
        "api-reference/users",
        "api-reference/posts",
        "api-reference/webhooks"
      ]
    }
  ]
}

How this configuration works:

Documentation Anchor (/docs/*)
- Shows “Getting Started” and “Core Concepts” groups
- Perfect for onboarding and conceptual content
Components Anchor (/components/*)
- Shows “Display Components” and “Layout Components” groups
- Focused view for component reference
API Reference Anchor (/api-reference/*)
- Shows “Authentication” and “Endpoints” groups
- Dedicated space for API documentation
Discord Anchor (external link)
- Links directly to external community
- No navigation filtering since it’s external

Real-World Example: Developer Portal

Here’s how a complete developer portal might use anchors for navigation:

{
  "name": "Developer Portal",
  "anchors": [
    {
      "name": "Docs",
      "icon": "book",
      "url": "docs"
    },
    {
      "name": "SDK Reference",
      "icon": "code",
      "url": "sdk"
    },
    {
      "name": "API Playground",
      "icon": "flask",
      "url": "playground"
    },
    {
      "name": "Tutorials",
      "icon": "graduation-cap",
      "url": "tutorials"
    }
  ],
  "navigation": [
    // Docs section - general documentation
    {
      "group": "Overview",
      "pages": ["docs/welcome", "docs/getting-started"]
    },
    {
      "group": "Integration",
      "pages": ["docs/webhooks", "docs/authentication", "docs/rate-limits"]
    },
    // SDK section - language-specific guides
    {
      "group": "JavaScript SDK",
      "pages": ["sdk/js/installation", "sdk/js/quickstart", "sdk/js/methods"]
    },
    {
      "group": "Python SDK",
      "pages": ["sdk/python/installation", "sdk/python/quickstart", "sdk/python/methods"]
    },
    {
      "group": "Ruby SDK",
      "pages": ["sdk/ruby/installation", "sdk/ruby/quickstart", "sdk/ruby/methods"]
    },
    // Playground section - interactive tools
    {
      "group": "API Explorer",
      "pages": ["playground/endpoints", "playground/test-environment"]
    },
    {
      "group": "Code Samples",
      "pages": ["playground/examples", "playground/templates"]
    },
    // Tutorials section - step-by-step guides
    {
      "group": "Beginner Tutorials",
      "pages": ["tutorials/first-api-call", "tutorials/basic-crud"]
    },
    {
      "group": "Advanced Tutorials",
      "pages": ["tutorials/batch-processing", "tutorials/real-time-updates", "tutorials/custom-webhooks"]
    }
  ]
}

Each anchor creates its own navigation context. Users clicking between anchors will see the sidebar update to show only the relevant groups for that section, creating a focused and organized documentation experience.

Common Issues and Solutions

This happens when page paths don’t include the anchor’s URL prefix. Update your navigation configuration:

// ❌ Incorrect - pages will appear under all anchors
{
  "group": "Components",
  "pages": ["accordion", "cards"]
}

// ✅ Correct - pages will only appear under "components" anchor
{
  "group": "Components",
  "pages": ["components/accordion", "components/cards"]
}

Anchors work alongside other navigation elements. Learn more about:

Navigation - Configure main sidebar navigation groups and pages
Global Settings - Set up branding, colors, and overall site configuration
Page Settings - Configure individual page properties

What are Anchors?

How Anchors Control Navigation Sidebars

URL-Based Navigation Grouping

Example: Multiple Navigation Contexts

Configuration

Basic Structure

Anchor Properties

Top Anchor Configuration

Default Top Anchor

Customizing the Top Anchor

Top Anchor Properties

Example Configurations

Use Cases

1. Section Your Documentation with Automatic Navigation Grouping

2. External Resources

3. Branded Anchors

Best Practices

Limit the Number

Use Clear Labels

Prioritize Important Content

Consider Visual Hierarchy

Test External Links

Styling Anchors

Examples

Complete Configuration with Navigation Grouping

Real-World Example: Developer Portal

Troubleshooting Anchor Navigation

Common Issues and Solutions

On this page

​What are Anchors?

​How Anchors Control Navigation Sidebars

​URL-Based Navigation Grouping

​Example: Multiple Navigation Contexts

​Configuration

​Basic Structure

​Anchor Properties

​Top Anchor Configuration

​Default Top Anchor

​Customizing the Top Anchor

​Top Anchor Properties

​Example Configurations

​Use Cases

​1. Section Your Documentation with Automatic Navigation Grouping

​2. External Resources

​3. Branded Anchors

​Best Practices

Limit the Number

Use Clear Labels

Prioritize Important Content

Consider Visual Hierarchy

Test External Links

​Styling Anchors

​Examples

​Complete Configuration with Navigation Grouping

​Real-World Example: Developer Portal

​Troubleshooting Anchor Navigation

​Common Issues and Solutions

​Related Configuration

On this page

What are Anchors?

How Anchors Control Navigation Sidebars

URL-Based Navigation Grouping

Example: Multiple Navigation Contexts

Configuration

Basic Structure

Anchor Properties

Top Anchor Configuration

Default Top Anchor

Customizing the Top Anchor

Top Anchor Properties

Example Configurations

Use Cases

1. Section Your Documentation with Automatic Navigation Grouping

2. External Resources

3. Branded Anchors

Best Practices

Styling Anchors

Examples

Complete Configuration with Navigation Grouping

Real-World Example: Developer Portal

Troubleshooting Anchor Navigation

Common Issues and Solutions

Related Configuration