Custom CSS

If you need more control than frontmatter and built-in components give you, DocsAlot can load a root custom.css file for your docs site.

We already use this pattern in the DocsAlot docs. The custom page mode example at /settings/page-modes/custom is styled by the root custom.css file in this docs project.

​

How it works

• Put custom.css at the root of your docs folder, next to layout.json and index.mdx.
• DocsAlot automatically loads the file in local preview and in hosted docs when it exists.
• You do not need to add a field in layout.json.
• The stylesheet is global, so the safest pattern is to scope your rules to a page wrapper class.

​

File placement

your-docs/
├── custom.css
├── layout.json
├── index.mdx
└── settings/

​

A good pattern

Use custom.css when you want a more curated page, especially with mode: "custom".

​

1. Add a page wrapper

---
title: "Home"
mode: "custom"
---

<div className="landing-page">
  <section className="landing-page__hero">
    <h1>Build polished docs pages inside your docs site.</h1>
    <p>Keep the top navbar, remove the rest of the chrome, and style the page yourself.</p>
  </section>
</div>

​

2. Style that wrapper in custom.css

.landing-page {
  width: 100%;
  max-width: 72rem;
  margin: 0 auto;
  padding: 3.5rem 1.5rem 0;
}

.landing-page__hero {
  padding: 4rem 0;
  border-top: 1px solid rgb(226 232 240);
  border-bottom: 1px solid rgb(226 232 240);
}

.landing-page__hero h1 {
  margin: 0;
  font-size: clamp(2.5rem, 5vw, 3.75rem);
  line-height: 1;
}

​

Why scoping matters

custom.css is loaded for the site, not only for one page.

That means selectors like .landing-page__hero are safer than broad rules like h1, p, or .prose h1, unless you intentionally want a site-wide override.

​

Best use cases

• splash pages and homepages
• onboarding-style entry pages
• layout tweaks for custom, center, or frame pages
• page-specific footers, CTA sections, and hero layouts

​

What to avoid

• unscoped selectors if you only mean to style one page
• using custom.css for custom JavaScript behavior

DocsAlot supports custom CSS here, but not custom JS.

​

Start simple

Most pages do not need much CSS. Start with:

1. a page wrapper class
2. one or two layout sections
3. only the overrides you actually need

If you are building a splash-style page, start with Page Modes and then use custom.css for the pieces that need a more tailored layout.