docusaurus-theme-pixelite

A stylesheet-only theme for Docusaurus 3. It reworks the classic preset's typography and layout rather than replacing any component, so it composes with whatever else a site is running, including docusaurus-theme-openapi-docs.

Modelled on the proportions of docs.sentry.io: a flat type scale with headings at weight 500, borderless inline code, dark code blocks in both colour modes, and a fixed three-column assembly centred in the viewport. None of the colours are Sentry's; every hue resolves from one variable.

Install

npm install docusaurus-theme-pixelite

// docusaurus.config.ts
themes: ["docusaurus-theme-pixelite"],

That is the whole installation. The theme ships its CSS through getClientModules(), so there is nothing to add to customCss.

Two companion settings

Code blocks are dark in both colour modes, which means light mode needs a dark Prism theme or the tokens vanish into the background:

prism: {
  theme: prismThemes.palenight,
  darkTheme: prismThemes.palenight,
},

And the type scale assumes a humanist sans. If you have no opinion, the theme falls back to the system stack; Inter and JetBrains Mono are what it was drawn against:

stylesheets: [
  {
    href: "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap",
    type: "text/css",
  },
],

Retheming

Set --pdt-accent and you are done. The sidebar's active row, the navbar underline, the table of contents marker, links, card hovers and focus rings all derive from it.

Put your overrides in clientModules, not customCss. Docusaurus appends a site's own client modules after every plugin's, so that file wins; customCss runs earlier and loses to the theme.

clientModules: [require.resolve("./src/css/brand.css")],

/* src/css/brand.css */
:root {
  --ifm-color-primary: #25a777;
  --pdt-code-fg: #106a93;
}

[data-theme="dark"] {
  --ifm-color-primary: #23c78b;
  --pdt-surface: #0e1320;
}

The knobs worth knowing

| Variable | Default | Effect | | --- | --- | --- | | --pdt-accent | var(--ifm-color-primary) | Every accented surface. | | --pdt-text-base | 15px | Root size. Everything else is rem, so this scales the page. | | --pdt-content-width | 1100px | Width of the prose column. | | --pdt-content-gutter | 2rem | Space between the sidebar's border and the first character. | | --pdt-sidebar-width | 280px | Left nav. Also feeds Docusaurus's --doc-sidebar-width. | | --pdt-toc-width | 250px | Right table of contents. Set to 0px when hiding it. | | --pdt-toc-display | block | Set to none to drop the right column and give the space to the prose. | | --pdt-weight-heading | 500 | Raise to 600 for a heavier page. | | --pdt-code-block-bg | #1f1b2e | Set to var(--pdt-surface-sunken) for light code blocks, and restore a light Prism theme if you do. | | --pdt-code-fg | #9c5f99 | Inline code tint. | | --pdt-method-* | per verb | The HTTP verb pills in the API sidebar. |

What is in the box

| File | Covers | | --- | --- | | tokens.css | Every measurement and colour, plus the Infima remapping. Start here. | | typography.css | Prose: headings, lists, tables, inline code, images, kbd. | | layout.css | Navbar, sidebar, content column, right table of contents, footer. | | components.css | Code blocks, admonitions, tabs, breadcrumbs, pagination, cards, diagrams. | | api.css | docusaurus-theme-openapi-docs restyling. Inert without it. | | diagram-zoom.js | Click a Mermaid diagram to open it full screen. Inert without diagrams. |

Navbar section highlighting

The active top-level navbar item gets an underline. For it to light up across a whole section rather than on one URL, each item needs an activeBaseRegex, and a dropdown needs a to of its own or it never takes an active state at all. Leave the regex unanchored: category landing pages live at /category/<slug>, outside the section's own path.

{ to: "/guides/intro", label: "Guides", position: "left",
  activeBaseRegex: "/(guides|concepts)" }

Diagrams

Mermaid sizes its SVG to the diagram's own content, which strands a wide flowchart at half scale in the middle of a wide column. Diagrams here fill the column, and clicking one opens it full size in a stage that scrolls. Esc or a click outside closes it, and the container is keyboard-focusable.

Notes for anyone editing the CSS

Two things will bite you, both silently.

Docusaurus emits its CSS modules after client modules. A single [class*="..."] match ties on specificity with Docusaurus's own module rule and loses on source order, !important included. That is why several selectors are doubled ([class*="x_"][class*="x_"], :root:root, .hash-link.hash-link). It is not a typo, and removing the duplication reverts the rule without any error.

--ifm-pre-background is not private to code blocks. docusaurus-theme-openapi-docs uses it for the "try it" request-form chrome, so pointing it at a dark code colour turns that whole panel black. The dark treatment lives on .theme-code-block instead.

Those hashed module names are stable across the 3.x line but are not a public API. A major Docusaurus upgrade is the place to recheck them.

Licence

MIT.