@scality/rspress-docs-tooling
v0.16.0
Published
Shared Rspress theme and build preset for Scality documentation sites
Keywords
Readme
@scality/rspress-docs-tooling
Shared Rspress v2 theme and build preset for Scality documentation sites, built on @scality/core-ui.
Entry points
| Import | Runs | Used by |
| --- | --- | --- |
| @scality/rspress-docs-tooling/theme | the browser | every documentation site |
| @scality/rspress-docs-tooling/preset | the build | sites with remark plugins and post-build passes |
| @scality/rspress-docs-tooling/portable-base (and the rspress-portable-base CLI) | after the build | sites served from more than one URL prefix |
There is no root export: a site that only renders pages never resolves the build-time half, so it cannot end up in a browser bundle.
Install
npm install @scality/rspress-docs-tooling@scality/core-ui comes with the package. react, react-dom, @rspress/core
and styled-components are peers — npm installs them for you, and keeping
styled-components a peer is what guarantees a single copy beside core-ui's own.
Use
Create theme/index.tsx in your Rspress project (next to docs/):
export * from '@scality/rspress-docs-tooling/theme';That single line:
- Re-exports every component from
@rspress/core/theme-originalso the rest of the default theme keeps working. - Replaces
Layoutwith one that wraps the doc inCoreUiThemeProvider+ToastProvider. - Imports
@scality/core-ui/dist/index.css(Lato + Fira Code fonts, base styles). - Aligns Rspress's brand CSS variables to the core-ui dark theme tokens.
- Lays the page out fluid: sidebar on the left edge, outline on the right edge, the doc in between.
- Draws the sidebar like core-ui's product
Sidebarand themes every scrollbar withScrollbarWrapper. - Adds the Scality documentation footer (support links, social links, and the date the site was built).
- Opens every Mermaid diagram in a full-screen pan and zoom viewer on click.
- Lets wide tables scroll instead of squeezing their columns.
Brands
The layout defaults to artesca. Pass your product's brand by overriding Layout:
import { Layout as ScalityLayout } from '@scality/rspress-docs-tooling/theme';
export * from '@scality/rspress-docs-tooling/theme';
export const Layout = () => <ScalityLayout brand="ring" />;The brands are artesca, ring, adi, xdm and maestro, each with a light and
a dark variant. There is no prop taking a raw Core-UI theme: it could only restyle
the Core-UI components, while links, sidebar and tabs keep the brand's generated
colours. A different look means adding a brand to src/theme/brands.ts.
Version and sidebar links
version shows the documentation's version as a tag next to the navbar logo.
SidebarLinks lists documents that live outside the doc tree, such as release
notes or legal terms, under the sidebar; passed as afterSidebar it also
appears in the mobile drawer. A group without links is not rendered.
import { withBase } from '@rspress/core/runtime';
import { Layout as ScalityLayout, SidebarLinks } from '@scality/rspress-docs-tooling/theme';
export * from '@scality/rspress-docs-tooling/theme';
export const Layout = () => (
<ScalityLayout
brand="artesca"
version="4.4.0"
afterSidebar={
<SidebarLinks
groups={[
{ title: 'Terms and Conditions', links: [{ text: 'PDF', href: withBase('/terms.pdf') }] },
]}
/>
}
/>
);Feedback widget
UsersnapFeedback files documentation feedback against the product's own
Usersnap project, with the page, product, version and locale attached:
import {
Layout as ScalityLayout,
UsersnapFeedback,
} from '@scality/rspress-docs-tooling/theme';
export * from '@scality/rspress-docs-tooling/theme';
export const Layout = () => (
<>
<ScalityLayout brand="adi" />
<UsersnapFeedback spaceKey={SPACE_KEY} projectId={ADI_PROJECT_ID} />
</>
);spaceKey and projectId are required and ship with the consuming repository,
never with this package — the npm tarball is public. The component throws when
either is missing, because the alternative is feedback filed silently against
the wrong product.
product defaults to the brand; with neither a product nor the Scality
Layout, the widget does not load and logs why. version and locale are
omitted when empty. The page is read when the reader opens the widget, not
when it loads, and the button is re-shown on every client-side navigation.
Demoing core-ui components in MDX
@scality/core-ui touches window / document and uses heavy CSS — wrap interactive
demos in <NoSSR>:
import { NoSSR } from '@rspress/core/runtime';
import { Button } from '@scality/core-ui/dist/next';
<NoSSR>
<Button label="Click me" variant="primary" />
</NoSSR>Serving one build from any URL prefix
rspress bakes its base into every link, asset URL and the client router, so
a build only works at the path it was built for: a latest symlink next to a
versioned folder renders, but its links and routes resolve to that folder.
Build with a placeholder base (the default is /REPLACE_ME_PREFIX/), then run:
rspress build && rspress-portable-base doc_buildThe output then works at any prefix with no deploy-time rewrite: HTML, CSS
and Markdown URLs become relative, each page derives the base from its own URL
at load time, and the client bundle reads that value. 404.html derives it
from the first path segment that is a top-level entry of the build. The pass
fails if the bundle does not carry the base in exactly the two expected string
literals, so an rspress upgrade that changes them breaks the build instead of
the site.
Build
npm run build # rslib emits ESM + .d.ts + styles.css to dist/