Helping my wife set up a new blog, I found that while writing posts and publishing them on Publii is very straightforward, getting the page to look how you want is more obtuse. So I thought I'd share what I found to help others customize it without (as much) hunting through confusing menus.
For reference, here's the preview image for the default theme, "Simple":
This is the default homepage for the theme, and it has several pieces, each of which can be customized.
Some quick potential q&as
Hey, wait, what is this Publii thing?
Publii is a Static Site Generator, which basically means you can write some blog posts and hit a button to generate a whole website's worth of HTML and other files. The "static" part means the website's all built, you don't need any code running on the server to, say, get a list of posts, all that is done in advance - you can just take your static site and drag it into, say, Neocities, and it'll work. When you change it or add posts, hit the button to generate it again, and drag it onto your web host again - easy! I've been looking at Publii because other static site generators I've looked at require setting up some kind of code, usually javascript and HTML, but this is easy to install and write in, without having to write any code. Just write your posts in the editor, like a word processor, and it does all that for you.
Is this going to involve CSS?
Well, yes, but actually, no. There's a few things you can't really do, as far as I can tell, through Publii's interface, but can easily adjust through custom css. But you didn't really need to understand css, just copy what I provide here if you want, and at most fill in the colours you want it'll be fine.
What about other themes for Publii?
There's a few, though I haven't really played with them. You can browse them on the marketplace and some are free, many (especially ones designed for something besides blogging, like technical documentation) cost money, but since the Simple theme comes with the program and is a good layout for blogging, which many cohost users are wanting, I'm focusing on that.
Simple theme? I find it quite complicated
I initially found it hard to find the right places to make changes to this theme, because the names were confusing as someone that's dabbled in web design but isn't part of the industry. So let's break down some of the terms used by Publii.
Content: Posts, Pages, Tags, Menus, Authors
First off, there's a bunch of different ways to add stuff to your site. There's a whole list to the left, and while all you really need to use is Posts, it'll be useful to understand the differences, to understand your blog's layout.
You know them, you love them, posts are what we're here for. Because Publii is built around blogging, it has a lot of built in features around posts - it can automatically generate a list of them, they can have tags, you can select some as featured posts, etc.
So why are "Pages" a separate thing? "Pages" are separate from posts, aren't indexed automatically, and basically are designed to be their own, self-contained things, outside of the feed of posts - an About Page, or Contact Page, for example. Some pages can be generated automatically - if you don't set a specific "homepage", it will generate a list of posts under a header and make that your homepage - that's what the example above shows. It can also generate "Author" pages automatically based on the author bios (or bios) you have set up. But otherwise, basically, if you want something that's static and sits outside the "posts" feed and indexing, you can make it a page, and link to it from another page or from a menu.
Tags and Authors are straightforward, they're attached to posts and can be generated automatically (when you add a tag to a post, and the default author created when you make the site), or manually. Each post has a link to the attached author and tags, and you can add an image, description, etc to those generated pages if you want.
Finally, the last type of thing you can add to your site is Menus, which unlike the rest do not have their own pages - they show up on every other page. Rather than editing it directly, you can add items of different types, and submenus under those items - that's because you can set it as the main menu of the website, which renders differently on desktop or mobile browsers, or the footer menu at the bottom of every page.
Here, you can see a basic navigation menu, and then how it's rendered on the desktop and on mobile (note that on mobile, it's hidden until you press a menu button at the top-right, then it opens over the page).
As mentioned earlier, this is probably where you want to link to you static pages from - it can also link to other generated pages, specific posts or tags, or external links, whatever you want to be at the top (or bottom) of every page.
Images: Logo, Featured, Hero, Content, etc
This was the most confusing part for me, because some of it is explained in Publii's documentation and some is not because it's part of the theme. There's a bunch of images around the site, and they're set in different places around Publii and have different caveats. I'll try to explain each one briefly.
A Featured Image is the main image (optionally) attached to a page, post, tag, or author. You don't put it in the post itself, but select it under the post's settings - this is important because it does two things, it appears in the list of posts (or tags or authors) to represent this post, and it appears at the top of the post (or etc) itself, under the title. If you add an image in the post itself, you can make it appear at the top, but it won't be associated with the post in other lists on the site. In the screenshot above, the image labeled "Featured (post)" is the featured image from that post, used as the thumbnail on this homepage.
The full-width image is part of what the Simple theme calls the Hero Section of the page, and the theme settings let you set the text and image for the hero section of the generated homepage, which is why I labelled the one here "Hero (theme)" - but if you were to open that first post, its featured image would be at the top, in the same place. The way the theme is set up, the hero image is always full-width and cropped to a maximum height, so be aware that if it's taller than it is wide, most of it will be cropped (though we can change that as I'll show below). The one on this homepage is set under the Theme Settings -> Layout -> "Hero Section" (that's also where you set the text above it).
Also not defined by Publii but by the theme is the *Logo for your website. That's going to be floating at the top-left of the page, as part of the navigation bar (opposite your main menu on the top-right, if you have one). That's set under the Theme Settings -> Basic Settings, right at the top of the settings page.
In addition to the featured image, each author has an Avatar - that's straightforward, it's the avatar for that author and will appear next to their name on posts they've written, as well as on their Author Page, in addition to their featured image.
Finally, there's **Content Images** which of course just means images what you put in the post or page itself. You can drag-and-drop, or hit the "insert/edit image" button, but it's worth noting that if you drag an image into the page, you can still double click it or hit the image button to set the options from the "insert/edit image" popup, including setting the size and the class options that let you float the image to the left or right (like the screenshot floating to the left of this paragraph!)
⚠️ Weird bug/unexpected behavior warning!
For some reason, when you put an image in the middle of a paragraph, Publii seems to always end the paragraph block it's in and start a new one. So you can't put images inline with text. However, you can still use the right-aligned image or left-aligned image classes to make it float next to the text underneath it.
Okay, but how do I make it look good?
Hopefully just knowing what the pieces of the webpage are and where to find them has already helped with setting it up how you like, but now that we have that foundation, we can go deeper with customizing the look.
Homepage
So, as said a few times, the theme will automatically generate a homepage made up of the "hero section" from the theme settings and a list of posts. You probably don't want that same header about your Blogging Journey™, so you can either modify this default homepage or replace it.
Replacing it is simple, you can create a Page and write whatever you like on it, then go to (confusingly) Site Settings -> SEO -> Homepage, and toggle "Set as homepage". Then select your custom homepage. If you still want to have a page listing all your posts, go to Site Settings -> URLs and make sure "Use pretty URLs" is toggled on and "Posts prefix" has something set, like "posts". This essentially moves the generated list of posts from /index.html to /posts/
Modifying it is also fairly simple, but more limited. As mentioned, you can go to the Theme Settings -> Layout -> Hero section, and change the text and image there. The text box here works like the post editor, but you can't actually insert images here. However, as my clever wife figured out, if you're okay interacting with a little HTML, you can just make a page, add an image to it, then hit the "<> HTML" button on the toolbar and copy the HTML from there and then hit the same button in your Hero Section text box and paste it in. You may also need to fix the URL in that html, if starts with "file:///". Just delete everything before "/media..." and it should work.
⚠️ Weird bug/unexpected behavior warning!
If you want to just delete that text and only have the image (or no header), be sure to add some spaces instead of leaving it empty! If the text box is totally empty, the page will revert to the default, this seems to be some kind of bug in Publii or the theme.
Finally, you can also adjust the height of the "hero" image on the layout page (by default it's "50vh" which means "50% of the View Height", ie half the browser window). But what if you want it (and every Featured Image on your posts) - to simply be as wide as it needs to be, without being stretched to full width and cropped to fit vertically? This is where some very simple CSS, finally, comes in. In Publii, just go to "Tools & Plugins" and "Custom CSS", and then paste one of these (depending on where you want it) into the text box:
/* left-aligned */
.hero__image-wrapper {width: fit-content;}
/* center-aligned */
.hero__image-wrapper {width: fit-content; margin:auto}
/* right-aligned */
.hero__image-wrapper {width: fit-content; margin-left:auto}
And it will instead shrink to fit the image into the max height.
Colors
The theme doesn't really offer a lot of colour customization, presumably so it can have different defaults for light and dark mode. However, if you want to have more direct control over your page's colours, we can add a little more CSS. First, in the Theme Settings, under Colors, set the colour scheme to either Light Mode or Dark Mode. Then, like above, go to the Tools & Plugins settings page, then Custom CSS, and paste this in:
:root {
--page-bg: #FFFFFF;
--text-color: #17181E;
--headings-color: #17181E;
--link-color: #17181E;
--link-color-hover: #D73A42;
--nav-link-color: #17181E;
--nav-link-color-hover: #17181E;
--logo-color: #17181E;
}
Those are the default colours for the most important parts of the page, they should be self explanatory, ie "page-bg" is page background. nav-link-color and nav-link-color-hover are for links in the main menu, and logo-color is for the name of your site on the top left of the page, if you don't have a logo image set. Now that you have that in your custom CSS, change those colours to whatever hex values you want, and they'll override the theme's settings.
If you want your page to also have separate light and dark mode settings, change the theme colour scheme back to "Auto", then also paste this into your custom CSS, under the previous block, and set it to your dark mode colours.
@media (prefers-color-scheme: dark) {
:root {
--page-bg: #181818;
--text-color: #BFBFBF;
--headings-color: #EEEDED;
--link-color: #EEEDED;
--link-color-hover: #FFC074;
--nav-link-color: rgba(255,255,255,1);
--nav-link-color-hover: rgba(255,255,255,.7);
--logo-color: #FFFFFF;
}
}
But what if I want to do more, go deeper?
That's about as much as I can think of that's easy change - setting the content, the layout images, and overriding the colours. You can also just explore the theme settings and see what else I didn't think was important enough to explain, like, idk, Fonts (you can set them in the theme settings but adding custom fonts to there is more complicated than I feel like going into), Navbar height, etc.
Other than that, if you do know how to wrangle some CSS, well, now you know where to put it. You can use that to override whatever you want in the layout. If you really want to make changes, like changing the structure of the pages, then you're getting into Publii theme development, which is way outside the scope of this post. But I can point you in the right direction - you'll want to read about overriding theme files and maybe dig into the theme developer docs. I've only used overrides to just delete sections of a page I don't want, but I'm sure if you really wanted to you could just rewrite it from the ground up.
