Add/centralize "Site generation" documentation

[skierpage]

Information about what cobalt serve and cobalt build do is spread out between their usage, the docs on Assets/Pages/Posts, and the Configuration page. But site generation is the central feature of an SSG, it should be documented in one place instead of users running these commands to infer what they do.

I'll work on a merge request that adds as "Site generation" page.

[epage]

Could you describe what questions or challenges you had that led to feeling this documentation is needed?

This feels very low level and I'm having a hard time seeing how it fits into the narrative in helping users. I wonder if there is a way to re-frame this that could better help. If you know of similar pages on other static site generators, that could also serve as some inspiration.

[skierpage]

Could you describe what questions or challenges you had that led to feeling this documentation is needed?

Sure. My site still hosts many pages generated by old-skool Blogger (sample page) that I'm trying to convert to static site generation so I can modernize a handful of templates rather than 240 pages. I followed Cobalt's Start instructions and got an empty site with a home "index" page that makes no sense (cobalt init creates one post and it's a draft, so there's no content). ... ... what now? 🤔

First I got sucked into _defaults trying to figure out how to get cobalt new to make new pages from a template, then I tried to figure out what the collections.posts.pages iteration does. But what I actually needed to do was prep my existing site to start running certain pages through Cobalt's liquid site generation, then add frontmatter telling them to use a layout. The page I wrote tells people how to do that, addressing this bug.

I'm confident your documentation is better with what I wrote. You've built a nifty site generator, so tell people what it does rather than making them puzzle it out trying to extend cobalt init. (Separately, you could have cobalt init or cobalt skeleton create a more comprehensive site so there's more examples to look at.)

I started out with Zola, but realized that it really wants you to write Markdown files, wants pages that are paths not my-page-name.html, and prefers local assets for each page. Its Overview does an OK job of telling you what it does with the files that it tells you to make, but doesn't explain what it does with other kinds of files; I learned about its limitations by searching for what I wanted to do and seeing GitHub issues in search results. Cobalt is less opinionated, but unless someone writes a lot of "Let's turn an HTML page into a Liquid file", it is not obvious what to do.

Thanks for making Cobalt ❤️. (I'm just another dog on the Internet, but FWIW I've written 1,000s of pages of technical documentation in a previous life 😉 .)