Skip to content

Update some docs #111

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jer3m01 merged 6 commits into from
Oct 7, 2025
Merged

Update some docs #111

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
fc76c03
update extending-themes page and add new ref pages
LadyBluenotes Sep 21, 2025
67c6ba7
update first page
LadyBluenotes Sep 21, 2025
5f591f8
update some pages
LadyBluenotes Sep 22, 2025
3c0a267
update order
LadyBluenotes Sep 22, 2025
62fac40
markdown page fix
LadyBluenotes Sep 22, 2025
223ee14
style: format
jer3m01 Oct 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 64 additions & 10 deletions docs/app.config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,13 +111,17 @@ export default defineConfig(
link: "/add-to-existing",
},
{
title: "Deploy",
link: "/deploy",
title: "Configure Your App",
link: "/config",
},
{
title: "Project Structure",
link: "/structure",
},
{
title: "Deploy Your Site",
link: "/deploy",
},
],
},
{
Expand Down Expand Up @@ -162,6 +166,10 @@ export default defineConfig(
title: "Reference",
collapsed: false,
items: [
{
title: "Configuration Options",
link: "/config",
},
{
title: "Frontmatter Config",
link: "/frontmatter",
Expand All @@ -181,21 +189,67 @@ export default defineConfig(
link: "/default-theme",
},
{
title: "Sidebar",
link: "/default-theme/sidebar",
},
{
title: "Article",
link: "/default-theme/article",
title: "CSS Variables",
link: "/default-theme/css-variables",
},
{
title: "Footer",
link: "/default-theme/footer",
title: "Components",
collapsed: false,
items: [
{
title: "Article",
link: "/default-theme/article",
},
{
title: "Features",
link: "/default-theme/features",
},
{
title: "Footer",
link: "/default-theme/footer",
},
{
title: "Header",
link: "/default-theme/header",
},
{
title: "Hero",
link: "/default-theme/hero",
},
{
title: "Last Updated",
link: "/default-theme/last-updated",
},
{
title: "Link",
link: "/default-theme/link",
},
{
title: "Locale Selector",
link: "/default-theme/locale-selector",
},
{
title: "Sidebar",
link: "/default-theme/sidebar",
},
{
title: "Table of Contents",
link: "/default-theme/toc",
},
{
title: "Theme Selector",
link: "/default-theme/theme-selector",
},
],
},
{
title: "Landing",
link: "/default-theme/landing",
},
{
title: "Layout",
link: "/default-theme/layout",
},
],
},
],
Expand Down
86 changes: 43 additions & 43 deletions docs/src/routes/guide/(customization)/extending-themes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,70 +4,69 @@ title: Extending Themes

# Extending Themes

If you'd like to customise an existing theme,
you can define a custom theme that extends it.
The custom theme's `Layout` should render the original theme's `Layout` component,
but apart from that you can treat it as a regular theme.
You can extend the default theme if you'd like to preserve the default theme's functionality while adding your own customisations.
SolidBase offers the ability to extend this theme, allowing you to build upon its existing features without starting from scratch.
For example, these docs [extend the default theme](https://github.com/kobaltedev/solidbase/blob/main/docs/app.config.ts#L7) to add [OpenGraph](https://ogp.me) tags

:::info
The theme used for these docs
[extends the default theme](https://github.com/kobaltedev/solidbase/blob/main/docs/app.config.ts#L7)
to add [OpenGraph](https://ogp.me) tags!
:::
## Create an Extended Theme

## Creating Extended Themes
To extend the default theme, you must define a custom theme using `defineTheme`, setting its extends property to the `defaultTheme`, imported from `@kobalte/solidbase/default-theme`, and configuring the `componentsPath` property to point to the folder housing your custom theme's components.

These examples will extend the default theme as an example.
```ts
<!-- app.config.ts -->
import { defineTheme } from "@kobalte/solidbase/config";
import defaultTheme from "@kobalte/solidbase/default-theme";

const customTheme = defineTheme({
componentsPath: import.meta.resolve("./src/custom-theme"),
extends: defaultTheme,
}),
```

Define a custom theme with `defineTheme` and provide the original theme's definition to `extends`:
Once the theme is defined, you can set it as the active theme in your SolidBase config, using the `createWithSolidBase` helper to wrap your configuration:

```ts
<!-- app.config.ts -->
import { defineTheme } from "@kobalte/solidbase/config";
import defaultTheme from "@kobalte/solidbase/default-theme";

const customTheme = defineTheme<CustomThemeConfig>({
componentsPath: import.meta.resolve("./custom-theme"),
extends: defaultTheme
});
const customTheme = defineTheme({
componentsPath: import.meta.resolve("./src/custom-theme"),
extends: defaultTheme,
}),

export default defineConfig(
createWithSolidBase(customTheme)(
// your solidbase configuration
)
);
```

Add a `Layout` file inside the `componentsPath` folder that renders the original theme's `Layout`:
To complete the setup, in the folder specified by `componentsPath`, create a `Layout` file that re-exports the default theme's `Layout` component. In this file, you can add any custom logic or components you'd like to appear on every page, so long as you render the `Layout` component somewhere in the returned JSX.


```tsx
<!-- Layout.tsx -->
import { Layout } from "@kobalte/solidbase/default-theme/Layout";

export default function (props: ComponentProps<typeof Layout>) {
// do whatever and render whatever you want as long as `Layout` gets rendered

return <Layout {...props} />
}
```

## Extending the Default Theme

The default theme provides multiple methods of customisation,
which we'd recommend configuring with a custom theme that extends it.
## Customizing the CSS

### Customising CSS
The default theme uses CSS variables for theming that you can override in your own CSS file. To add your own CSS file, simply import it in your `Layout` file.

The default theme's CSS can be customised using CSS variables:

```tsx
<!-- Layout.tsx -->
```tsx tab title="Layout.tsx"
import Layout from "@kobalte/solidbase/default-theme/Layout";
// this import must be below the Layout import

import "./custom.css";

export default function () { ... };
```

<br />

{/* prettier-ignore */}
```css
<!-- custom.css -->
```css tab title="custom.css"
html {
--sb-background-color: white;
}
Expand All @@ -77,8 +76,7 @@ html[data-theme*="dark"] {
}
```

The full list of overridable CSS variables is in the
[default theme's source code](https://github.com/kobaltedev/solidbase/blob/main/src/default-theme/variables.css).
To see the full list of available CSS variables, refer to the [CSS Variables reference](/reference/default-theme/css-variables).

### Using Different Fonts

Expand All @@ -88,7 +86,7 @@ The default theme uses a few fonts:
- [Inter](https://rsms.me/inter) for text
- [JetBrains Mono](https://www.jetbrains.com/lp/mono/) for code

To stop these fonts from being loaded, set `themeConfig.fonts` to `false`:
To disable these fonts, set the `fonts` option to `false` in your SolidBase config:

```ts
<!-- app.config.ts -->
Expand All @@ -102,7 +100,7 @@ export default defineConfig(withSolidBase(
))
```

You can then provide your own fonts:
You can then provide your own fonts by overriding the variables in the CSS file you imported in your `Layout` component.

{/* prettier-ignore */}
```css
Expand All @@ -116,10 +114,10 @@ html {

### Overriding Components

In addition to using a custom `mdx-components` file to override the components available in markdown files,
the components [listed here](https://github.com/kobaltedev/solidbase/blob/main/src/default-theme/context.tsx)
can be overriden using `DefaultThemeComponentsProvider`.
Most of these components are used as part of the layout, rather than inside your markdown files.
Beyond the markdown components, you can also override components used in the layout. These components can be overridden using the `DefaultThemeComponentsProvider` and passing in your custom components.

The full list of components that can be overridden is available in [the reference documentation](/reference/default-theme#components).


```tsx
<!-- Layout.tsx -->
Expand All @@ -130,7 +128,9 @@ import Article from "@kobalte/solidbase/default-theme/components/Article";
export default function (props: ComponentProps<typeof Layout>) {
return (
<DefaultThemeComponentsProvider
components={{ Article: CustomArticle }}
components={{
Article: CustomArticle,
}}
>
<Layout {...props} />
</DefaultThemeComponentsProvider>
Expand Down
0 docs/src/routes/guide/dev.mdx → docs/src/routes/guide/(features)/dev.mdx
View file
Open in desktop
File renamed without changes.
50 changes: 50 additions & 0 deletions docs/src/routes/guide/(features)/i18n.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
---
title: Internationalisation
---

# {frontmatter.title}

SolidBase has built-in i18n support which can be configured in the root config:

```ts
export default defineConfig(
createWithSolidBase(theme)(
/* SolidStart options */
{
...
},
/* SolidBase options */
{
...
lang: "en", // default lang without route prefix
locales: {
fr: {
label: "Français",
themeConfig: {
...
},
},
},
...
}
)
);
```

## Creating Localized Routes

To create localized routes, simply create a folder with the locale code inside the `src/routes` directory. All files within this folder will be served under the corresponding locale prefix. For example, files in `src/routes/fr` will be accessible under the `/fr` path. The default locale (e.g., `en`) will not have a prefix and will be served from the root path. The folder structure would look like this:

```
src
└─ routes
├─ fr
│ ├─ index.mdx
│ └─ about.mdx
├─ index.mdx
└─ about.mdx
```

## Theme Configuration

Similar to the theme configuration for the default locale, you can provide a `themeConfig` for each locale to customize the theme for that specific language. To learn more about how to adjust the theme configuration, refer to the [Theme Configuration section within the config page](/guide/config#theme-configuration).
Loading