Observations when creating a new site from scratch with perplex

[danielfdickinson]

Hi. Thank you for designing this very professional theme and making it available. I've been frustrated with available themes and seem to end up with quite a bit of need to change them to satisfy all my wants. So far, from poking around, it looks like you have covered most of the things I need (and those probably can be handled having my own add-on module, for the things that aren't suitable for 'upstreaming' to you.

In any event I am a reasonably experienced Hugo user and decided to have a go at using the theme 'from scratch' with (by default) nothing except hugo new site ... and following the instructions and documentation available. I'll make notes here as a I go, much of which should be converted to proper issues (mostly for the docs) and/or pull requests. I hope you find this information useful.

• I am using perplex a module so needed to do `hugo mod init [path-to-site-repo]'
• I added move hugo.toml to config/_default/hugo.toml (for various reasons I prefer toml and it is the Hugo default, so I didn't convert it to config/_default/hugo.yaml as seems to be the preference for perplex's docs/archetypes (For those I'll stick with yaml since it's the theme default)).
• The first thing I noticed after creating the first blog post were the following message:

WARN  mod-resource/func/get-with-params: Can't find the resource "featured". See categories.
WARN  mod-resource/func/get-with-params: Can't find the resource "featured". See tags.

I realized that was because I forgot -D so there was effectively an empty site. It might be helpful to mention the error messages in a troubleshooting section, to suggest 'check -D'.

Open for full output of `hugo serve`

Watching for changes in C:\Users\danie\Build\{bowman2001-perplex,pp-princesandmadmen}
Watching for config changes in C:\Users\danie\Build\pp-princesandmadmen\config\_default, C:\Users\danie\Build\bowman2001-perplex\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-meta\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-replacements\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-open-in-vscode\v2\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-katex\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-mermaid\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-simple-icons\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-material-symbols\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-pangram\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-wrap\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-image\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-resource\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-error-message\hugo.yaml, C:\Users\danie\Build\pp-princesandmadmen\go.mod
Start building sites …
hugo v0.121.1-00b46fed8e47f7bb0a85d7cfc2d9f1356379b740+extended windows/amd64 BuildDate=2023-12-08T08:47:45Z VendorInfo=gohugoio

WARN  mod-resource/func/get-with-params: Can't find the resource "featured". See categories.
WARN  mod-resource/func/get-with-params: Can't find the resource "featured". See tags.

                   | EN
-------------------+------
  Pages            |   5
  Paginator pages  |   0
  Non-page files   |   0
  Static files     | 380
  Processed images |   0
  Aliases          |   0
  Sitemaps         |   1
  Cleaned          |   0

Built in 2688 ms
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

For reference here is the output with `hugo -D --navigateToChanged`

Watching for changes in C:\Users\danie\Build\{bowman2001-perplex,pp-princesandmadmen}
Watching for config changes in C:\Users\danie\Build\pp-princesandmadmen\config\_default, C:\Users\danie\Build\bowman2001-perplex\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-meta\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-replacements\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-open-in-vscode\v2\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-katex\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-mermaid\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-simple-icons\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-material-symbols\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-pangram\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-wrap\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-image\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-resource\hugo.yaml, C:\Users\danie\Build\bowman2001-perplex\_vendor\github.com\bowman2001\hugo-mod-error-message\hugo.yaml, C:\Users\danie\Build\pp-princesandmadmen\go.mod
Start building sites …
hugo v0.121.1-00b46fed8e47f7bb0a85d7cfc2d9f1356379b740+extended windows/amd64 BuildDate=2023-12-08T08:47:45Z VendorInfo=gohugoio

WARN  mod-resource/func/get-with-params: Can't find the resource "featured". See blog\2023-12-10-trying-a-new-website-theme.md.
WARN  mod-resource/func/get-with-params: Can't find the resource "featured". See blog.
WARN  mod-resource/func/get-with-params: Can't find the resource "featured". See tags.
WARN  mod-resource/func/get-with-params: Can't find the resource "featured". See categories.

                   | EN
-------------------+------
  Pages            |   8
  Paginator pages  |   0
  Non-page files   |   0
  Static files     | 380
  Processed images |   0
  Aliases          |   0
  Sitemaps         |   1
  Cleaned          |   0

Built in 2615 ms
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Also, the lack of a landing page at the site root in the default config could use some documentation for a quick solution (until site builder is able and willing to design their own home page layout).

E.g. mention the trick from perplexdoc repo, and show the example metadata for making a blog or news section the default root url.

Specifically, for a section (such as news), create (if not already present) the list page (e.g. news/_index.md) which includes in its metadata:

url: /

More later, but this is getting long.

[danielfdickinson]

I got mixed up by the authors. I was expecting authors to be a section with separate author pages, but the configuration is actually using taxonomy and terms and requires updating the taxonomies configuration. This could be better documented. The main trick is that hugo.yaml needs

taxonomies:
  categories: categories
  tag: tags
  series: series
  author: authors

[bowman2001]

Yes, the taxonomies configuration doesn’t get set by default and there is no way of doing so. The theme has this section, but every project needs either a copy or explicitly ask for the merge:

taxonomies:
  _merge: deep

Will document.

[danielfdickinson]

Yeah, Hugo is great, but can't automagically do the taxonomies. I didn't realize in your configs what the deep merge was for, so thank you for putting documenting this on you to do list.

[danielfdickinson]

Another thing that threw me off was that the menu only applies to the 'docs' section. It was driving me bonkers why the hamburger (≡) was not appearing on the main page (which I have as the blog index page via url: / in blog/_index.md).

On a related note, it might be worth mentioning that one cannot have pre on the top-level of the main menu as the CSS is not configured for the SVG icons in the top nav/title bar (adding pre to these menus also breaks the indicator of what section one is in (i.e. the 'active' indicator).

[bowman2001]

1. About the sidebar menu: The documentation is the only section which has a menu, and it should only appear on its own pages.

   I see your point, nonetheless: The UX is not coherent, one would expect a sidebar menu for the other sections, too. This would be a new feature for all other sections. Because there is no given menu structure, a flat list ordered by date would be the first idea that comes to mind.

2. I would like to keep icons out of the primary menu because it is always visible, and icons reduce the amount of available space. The difference is noteworthy, you’re right.

[danielfdickinson]

For 1. I wonder if a conditional year/month hierarchy (if there are 'enough' pages that fit in a particular bin) would be useful. Also, I don't consider this urgent, now it's more of a 'too be aware of' than a major problem.

For 2. I understand keeping the icons out (I saw how much space was taken up where the icon would have been had it appeared, and it is too much for that top nav bar), it's just another of the things that would be handy to know about instead of finding out by it not working. Not urgent, but worth mentioning, I think.

[bowman2001]

For 1. To put the currently non-existent archive in the sidebar is a possibility.

For 2. I did remove the code for the pre icon from the top menu template for now.

[danielfdickinson]

I've got the skeleton of my site working now (pagefind is a wonderfully easy to get going with the info you have, though I .gitignore static/pagefind and copy the public/pagefind there so that pagefind works with hugo serve but does not pollute my repo with generated content).

Now to browse around and 'borrow' more of your configs, and merge in some things from my existing site, and add the content from the old site.

It'll take a bit, but all in all, fairly easy to get the site working OOTB.

Thank you!

[bowman2001]

I’m very glad you like the theme! Thanks for your comments and bug reports.

[danielfdickinson]

And thank you for taking the time to read my comments and think about them.