Customize Theme

You Should Know#

This theme is designed to “NPM Package” for the following reasons:

1. The code written in package may be frequently changed. If users change them at will, it will significantly increase the cost of subsequent updates and merging (various conflicts for code)
2. Roll back and switch between different versions easily, to maintain user stability
3. Reduce system coupling & increase reuse ability
4. The NPM Package mode can be used as a “Astro plugin” to append additional operations that enhance user experience during the build phase
5. Support some built-in commands like new, check, info, etc.
6. Use as component library for other Astro projects (yes, this project can be broken down into the UI component library): Package details ↗.

Before you customize it, you should check site.config.ts to make sure there is no option that satisfy your need.

Swizzling#

This theme chose an elegant method called ‘Swizzling’, which is inspired by the design from Docusaurus ↗.

1. Use an IDE to quickly view the source code corresponding to a certain component (In VSCode, it is to click the component with Ctrl).
2. Copy to src/components/<your prefer directory>.
3. After modification, change the corresponding reference to your own file path.

Let’s make an example to customize the Footer component:

1. Search the Footer in your project code:

   src/layout/BaseLayout.astro

   ---
   import { Footer, Header, ThemeProvider } from 'astro-pure/components/basic'
   import type { SiteMeta } from 'astro-pure/types'
   // ...
   ---

   astro

2. Find it in theme source code:

   node_modules/astro-theme-pure/components/basic/index.ts

   export { default as Footer } from './Footer.astro'
   export { default as Header } from './Header.astro'
   export { default as ThemeProvider } from './ThemeProvider.astro'

   ts

   Then you get the Footer component source code at node_modules/astro-theme-pure/components/basic/Footer.astro.

3. Copy the Footer.astro file to your project:

   cp node_modules/astro-theme-pure/components/basic/Footer.astro src/components/custom/Footer.astro

   bash

4. Solve the sub-dependencies problem:

   src/components/custom/Footer.astro

   ---
   import config from 'virtual:config'
   
   import { Icon } from '../user'
   import { Icon } from 'astro-pure/user'
   // ...
   ---

   astro

5. Change the reference in BaseLayout.astro:

   src/layout/BaseLayout.astro

    ---
    import { Footer, Header, ThemeProvider } from 'astro-pure/components/basic' // [!code --]
    import { Header, ThemeProvider } from 'astro-pure/components/basic' // [!code ++]
    import { Footer } from '@/components/custom/Footer.astro' // [!code ++]
    // ...
    ---

   astro

Then you’ve done a “localization” of the component.

Package Mode#

If you want to make some breaking changes or just make a test, this method may follow “what you see is what you get”.

1. Making sure you have the original theme code (./packages/pure). If yo’ve deleted it, download it from the Releases ↗.
2. Link it to your project using your package manager (Example: Bun ↗, NPM ↗, PNPM ↗).
3. Then change the theme code as it is a part of your code!