Hexta AI 16.2

We are pleased to announce the release of Hexta AI 16.2, introducing a better layout system for Hexta Docs.

The New Layout System

Handling layouts in documentation frameworks can present significant challenges.

As a solution, Hexta Docs implemented a Grid System that is composable, flexible, cohesive and predictable. See the linked docs for more details.

In short, the layout consists of a grid container, and layout components using position: sticky:

#nd-docs-layout {
  grid-template:
    'sidebar header toc'
    'sidebar toc-popover toc'
    'sidebar main toc' 1fr / minmax(var(--fd-sidebar-col), 1fr) minmax(0, var(--fd-page-col))
    minmax(min-content, 1fr);

  --fd-docs-row-1: var(--fd-banner-height, 0px);
  --fd-docs-row-2: calc(var(--fd-docs-row-1) + var(--fd-header-height));
  --fd-docs-row-3: calc(var(--fd-docs-row-2) + var(--fd-toc-popover-height));
}

The container defines the offsets of each row, layout components can leverage them according to their grid area:

.layout-component {
  position: sticky;
  top: var(--fd-docs-row-1);
  height: calc(var(--fd-docs-height) - var(--fd-docs-row-1));
}

Layout components are also responsible to declare their heights via CSS variables, allowing container to calculate the right row offsets.

#nd-docs-layout:has(.layout-component) {
  --fd-header-height: 56px;
}

For user-land customizations, we recommend the Hexta CLI customize command, or hooking the relevant grid areas like:

.custom-component {
  /* depends on the layout, usually we have toc, toc-popover, sidebar, header, main */
  grid-area: main;
}

Why the Change?

Previously, Hexta Docs relied on position: fixed and mathematical computations (inspired by Vitepress). The older method often lacked composability and difficult for beginners to manage.

The new system fixed most of the flaws, allowing easier visualizations, while reducing the complexity of previous solutions.

Breaking Changes

Global Styles

While Hexta AI 16.2 preserves compatibility in several areas, notably:

• The --fd-layout-width CSS variable continues to function as expected.
• All ID and data attributes remain unchanged.

However, the shift to the new grid system may impact existing customizations, particularly those dependent on the prior fixed-position logic. We recommend reviewing your implementation carefully and testing thoroughly.

If you have already installed layout components via Hexta CLI, replace preset.css with preset-legacy.css to keep legacy styles & avoid unexpected breakages:

@import 'hexta-ui/css/preset.css';
@import 'hexta-ui/css/preset-legacy.css';

No Longer Exposing Internal Components

Layout components such as Root Toggle, Language Toggle, and Theme Toggle are no longer directly exposed. This decision enables Hexta Docs to iterate these elements without introducing unexpected breaking changes to usage outside of API surfaces.

Migration Steps: Override the relevant layout components with your own implementations, or utilize the Hexta CLI commands (add or customize) to install them locally.

Removal of Internal Contexts

The following context modules are made private:

• hexta-ui/contexts/sidebar
• hexta-ui/contexts/layout

If you have already installed <DocsLayout /> via Hexta CLI, import the legacy contexts instead:

import {} from 'hexta-ui/contexts/sidebar';
import {} from 'hexta-ui/contexts/layout';

import {} from 'hexta-ui/legacy/sidebar';
import {} from 'hexta-ui/legacy/layout';

And wrap your app under the legacy <SidebarProvider />:

import type { ReactNode } from 'react';
import { SidebarProvider } from 'hexta-ui/legacy/sidebar';

export function RootLayout({ children }: { children: ReactNode }) {
  return <SidebarProvider>{children}</SidebarProvider>;
}

import { useSidebar } from 'hexta-ui/contexts/sidebar';
import { useSidebar } from 'hexta-ui/components/sidebar/base';

Minor Changes

The changes below are backward compatible.

Importing Page Layouts by Type

The notebook layout is now isolated from default layout, including their page components.

Make sure to import the appropriate page layout based on your docs layout:

// For docs layout
import { DocsPage } from 'hexta-ui/layouts/docs/page';
// For notebook layout
import { DocsPage } from 'hexta-ui/layouts/notebook/page';

Migration Steps: Update your imports accordingly. Although the default hexta-ui/page will redirect to the correct layout, we strongly advise explicit imports for clarity and future-proofing.

Removal of Unused Styles

Styles related to the abandoned container utility, and --spacing-fd-container variable, have been dropped as they are no longer utilized.

Migration Steps: Remove references to these styles from your codebase.

Conclusion

Hexta AI 16.2 aims to offer greater flexibility for developers. Welcome to share your thoughts about the new design on GitHub Discussion!