Tips for creating your own Publii theme from an existing one

File Tips For Custom Publii Theming.md

I'm working on a custom Publii theme that's derived from an existing theme, but doesn't make use of theme overrides. I'm making the changes directly to the theme files, because I want this to be a standalone theme by the end of my modifications.

As I learn new things, I'll add them to the list below. Let's assume we're starting from the "Simple" theme, and changing it to a new theme called "My-New-Theme"

1. Make sure the folder name for your theme and the name in config.json match:

Folder structure:

.
└── site name/
    └── input/
        └── themes/
            └──  ̶S̶i̶m̶p̶l̶e̶/ → My-New-Theme/

config.json:

{
    "name":  ̶"̶S̶i̶m̶p̶l̶e̶"̶  → "My-New-Theme",
    "version": "1.0.0",
    "author": "Name Nom",

If you don't do this, you'll end up with Rendering process failed errors, where the style.css won't be found (ENOENT: no such file or directory) because it's looking for it in the theme folder's name.

2. Rename the .lang.json file to match your theme name

.
└── site name/
    └── input/
        └── themes/
            └── My-New-Theme/
                    └──  ̶s̶i̶m̶p̶l̶e̶.̶l̶a̶n̶g̶.̶j̶s̶o̶n̶  → My-New-Theme.lang.json

If you don't do this, you'll end up with [MISSING TRANSLATION] text in your site:

3. Keep track of your changes with detailed notes

Make sure you're keeping track of what changes you're making to the existing theme. This will help with upgrading the theme in the future (in terms of cross-referencing the updated base theme against your modified version) and will be a lifesaver for future you.

Here's how I track my changes:

• Using git versioning in the theme folder itself (via VS Codium's built-in function)
• Adding comments: /* like this */ for CSS, // like this or /* like this */ for JavaScript, {{! like this }} for handlebars. I prepend comments about anything new that I've created with custom:, and anything modified is marked with mod:
• Some formats, like .json, don't accept comments. In those cases, I track my major modifications in a separate document or project management tool. I'm a fan of Appflowy (another FOSS tool), but Notion, Obsidian, etc. could work too.

4. For custom fonts: Be consistent with the name

To add a custom font to your Publii theme, per the docs, you'll need to make sure to:

1. Create a new folder in your site/input/themes/theme-name/assets/dynamic/fonts folder for the new font file(s) in .woff2 format. CloudConvert has worked for me to convert a ttf variable font to woff2.
2. Add the name of your font in the config.json sections for fontBody and fontHeadings
3. Add the font name and weight scale to theme-variables.js
4. Indicate whether the new font has an italic variation in dynamic-assets-mapping.js

Across these three locations: make sure to use a consistent name for the font, including for the .woff2 font file(s). For example, here's what I did for the font Source Serif 4:

assets/dynamic/fonts:

My-New-Theme/
├─ assets/
│  ├─ dynamic/
│  │  ├─ fonts/
│  │  │  ├─ sourceserif4/
│  │  │  │  ├─ sourceserif4-italic.woff2
│  │  │  │  ├─ sourceserif4.woff2

config.json:

 "name": "fontBody",
    "label": "Body font",
    "group": "Fonts",
    "value": "system-ui",
    "type": "select",
    "options": [
        {
            "label": "Source Serif 4",
            "value": "sourceserif4",
            "group": "Serif"
        },

theme-variables.js:

'sourceserif4': {
      name: 'Source Serif 4',
      family: '\'Source Serif 4\', serif',
      weight: '200 900',
      hasItalic: true
    },

Notice the consistent use of sourceserif4 vs Source Serif 4

5. Sub-menus

-1

6. Tips for Editing CSS

main.css, dev tools, Custom CSS

---

Found these tips helpful? Consider supporting my work so that I can keep going. 😊

Great, I am also working on building my own theme but don’t know where to start. Your post is an inspiration for me, and I hope to learn a lot from you. Thank you so much!

@ManhTuan689 Happy to hear it! Let me know if there's anything you'd like to learn about 😊