Rocket
On this page

Atlas Layouts#

Rocket ships atlas layouts as reusable docs-site affordances. They are useful when a Site Author wants a documentation-style site quickly but still wants to own project data, Pages, assets, and component documentation.

Atlas docs layout#

Use atlasDocLayout for ordinary documentation Pages:

import { atlasDocLayout } from '@rocket/js/layouts/atlasDoc.js';
import { siteData } from './siteData.js';

export const layout = pageData => atlasDocLayout(pageData, siteData);

The layout renders:

Required components export#

The atlas docs layout uses Registered Components for menus, table of contents, previous/next links, social links, and Web Awesome elements. Pages using the layout should export the matching component map:

import { atlasDocLayout } from '@rocket/js/layouts/atlasDoc.js';
export { atlasDocComponents as components } from '@rocket/js/layouts/atlasDoc.js';

When a Page also owns project components, spread the atlas components first:

import { atlasDocComponents } from '@rocket/js/layouts/atlasDoc.js';

const acmeButtonFile = new URL('../components/AcmeButton.js', import.meta.url).href;

export const components = {
  ...atlasDocComponents,
  'acme-button': {
    file: acmeButtonFile,
    className: 'AcmeButton',
    loading: 'server',
  },
};

Docs layout data#

Pass project-owned data into the layout:

import { resolve } from '@rocket/js/resolve.js';

export const siteData = {
  headerData: {
    logo: [
      resolve('./assets/acme-mark.svg', import.meta),
      resolve('./assets/acme-wordmark.svg', import.meta),
    ],
    socials: [
      {
        url: 'https://github.com/acme/acme-ui',
        name: 'GitHub',
        label: 'Open Source',
      },
    ],
  },
};

headerData.logo can contain one or two image URLs. With one image, atlas renders a single logo. With two images, atlas renders a mark and a wordmark.

headerData.socials is an array of { url, name, label? } entries. The name chooses the social icon when Rocket has a matching icon asset. The optional label shows visible text to the right of the icon. Omit label for an icon-only link.

Keep this data in your project. Do not import Rocket's docs-site docs/pages/globalData.js into a user site.

Local layout wrapper#

For larger projects, create one user-owned layout module and import it from Pages:

import { atlasDocComponents, atlasDocLayout } from '@rocket/js/layouts/atlasDoc.js';
import { siteData } from './siteData.js';

export { atlasDocComponents };

export const components = atlasDocComponents;
export const layout = pageData => atlasDocLayout(pageData, siteData);

Then Pages can use the local wrapper:

```js server
export const config = {
  path: '/components/button',
  metadata: { title: 'Button' },
};

import { layout } from '../docsLayout.js';
export { components } from '../docsLayout.js';
```

This keeps Rocket-owned imports in one place while the site owns the data and Pages.

Atlas hero layout#

Use atlasHeroLayout for a home Page with a hero and feature list:

import { atlasHeroLayout } from '@rocket/js/layouts/atlasHero.js';
export { atlasHeroComponents as components } from '@rocket/js/layouts/atlasHero.js';
import { siteData } from './siteData.js';

const heroData = {
  featuresData: [
    {
      icon: '1',
      title: 'Static content',
      description: 'Pages build to HTML by default.',
    },
  ],
  heroMainData: {
    logoWithText: '/assets/acme-wordmark.svg',
    logoNoText: '/assets/acme-mark.svg',
    sloganTop: 'Build docs with',
    sloganBottom: 'Acme UI',
    documentationLink: '/components/button',
    documentationText: 'Components',
    setupLink: '/setup',
    setupText: 'Setup',
  },
};

export const layout = pageData => atlasHeroLayout(pageData, { ...siteData, ...heroData });

The hero layout also expects footerData when the Page should render a footer. setupText and documentationText are optional; when omitted, the layout uses default button labels.

Atlas not found layout#

Use atlasNotFoundLayout for a static 404.html Page:

export const config = {
  path: '/404.html',
  metadata: { title: 'Page not found' },
  menu: false,
  discoverability: { sitemap: false },
  siteHeadMetadata: { indexing: 'noindex' },
};

import { atlasNotFoundLayout } from '@rocket/js/layouts/atlasNotFound.js';
export { atlasNotFoundComponents as components } from '@rocket/js/layouts/atlasNotFound.js';
import { siteData } from './siteData.js';

export const layout = pageData => atlasNotFoundLayout(pageData, siteData);

Static hosts such as Netlify, Cloudflare Pages, Vercel, and GitHub Pages can use the generated 404.html file as the custom Not Found response.

Web Awesome components#

Atlas docs components include Web Awesome components used by the layout. If a custom layout still wants package component registration, import the package component map directly:

import { webAwesomeComponents } from '@rocket/js/components/web-awesome.js';

export const components = {
  ...webAwesomeComponents,
};

Add Page-owned components to the same map when the Page contains both package components and local project components.

When to replace atlas#

Keep atlas when the project needs a working documentation shell and the layout shape fits.

Replace it with a custom layout when the site needs different information architecture, custom header behavior, custom accessibility affordances, or a visual system that should not inherit Rocket's docs-site layout choices.