docs: Generate docs with a static site using templ (rewrite of #401)

[nathan-hello]

Hey there. I forked the repo from @cugu and rewrote much of the go code. The site at https://cugu.github.io/templ/new/ is identical to what this produces. I didn't change any of the frontend. This is a remake from #549 because there was some issues with CI. This closes #153.

Notable changes:

• Broke down files into multiple folders, renamed functions and variables for clarity, reworked how the Page struct is created and used throughout the program. I think it's a more legible program because of these changes. I'm more than happy to go into more detail about the differences, or how the program works as a whole. The output of the html/static files is at docs/build/.
• Made the entire project within docs/ instead of docgen/, because I don't see the purpose in keeping around the docusaurus project if this is the direction we're going. This does mean that the lines changes is massive. Most of the deletions (~16k LOC) is just from the docusaurus package-lock.json vs the new package-lock.json which only depends on tailwind and tailwind/typography.
• Added a proper package.json for the two dependencies. This also means that there is an npm run build alias for running tailwind, running templ, and using the program to build the docs, and a npm run start alias for all of that except it also has the --local flag. This also means that xc docs-run and xc docs-build still works.
• Removed the _category_.json files. We get the order from the folder/file name (index.md is always 1). We get the label for folders from the folder name, and for files we get it from the first heading (whatever line that starts with #). The program (at docs/docs/main.go) that was generating these files seemed to be out of sync with what was actually there. We can generate the _category_.json files again if that's what we want, I would just need to know what the purpose of them are.
• The entrypoint is very simply go run main.go, with an optional flag for --local which will build all of the html files and start a localhost:8080 webserver for viewing them.

Notable problems:

• In using-react-with-templ, for example, the chart there doesn't have the right contrast on dark mode. Also some of the text is formatted as red instead of the color pallet the rest of the code blocks use (this is because of the tsx/typescript within the triple-tick, I didn't want to change any of the markdown in this pr because that's not within the scope I think)
• When searching, you can see the markdown formatting. It's a small detail, but I think it should only display the text.
• Clicking on the words on the left triggers the dropdown that displays the relevant articles, but clicking on the actual arrow doesn't.
• While there is a /quick-start/installation.html, if you were to go to /quick-start you get a 404. I would like to make it so that /quick-start/index.html is a page that has a snippet of the pages within it. This is because the Page struct for section pages (read: folders) doesn't actually have any content within it, it just has children which have content.

[nathan-hello]

Any way I could get some feedback/movement on this?

[a-h]

Thanks for picking this up! I haven't had chance to look through because I was focusing on the last release.

I feel like I've gotten back on top of most of the PRs and issues now, and will get to this soon. Sorry to be a blocker here.

[samueltuyizere]

This is great @nathan-hello ! For better DX, I'd suggest we add a new script in docs/package.json for dev that can use a combination of Air and templ generate --watch to have some sort of hot reloading while developing.

[joerdav]

I have some xc tasks in this repo for hot-reloading a website: https://github.com/joerdav/shopping-list

[nathan-hello]

@samueltuyizere I have this script in my personal repo. It runs tailwind watch, templ watch, and air at once, and puts the output of all of them to stdout. It provides me really great DX for working on my little project. I didn't put air in this because I figured that most people running it would run it once or twice to make sure the docs they wrote rendered right and not really work on the proper website. I can add air and the script and put it under npm run dev.

@a-h It's no problem, I very much get that the feature/fix PRs are more important than this rewrite.

[nathan-hello]

I tried for a bit to get air to work well and it's really tricky. I suspect that there is an air.toml that makes it work perfectly, but I can't get it there. It seems like it just doesn't care about templ changing the _templ.go files. Maybe because those changes happen so quickly after the initial .templ file being written, but the delay in air.toml is already 0ms. I'm very much okay with dropping air, because most people just want to verify their docs look okay.

I'm not sure what you all do in your templ and tailwind projects, but I am of the opinion that generated code is okay to ignore. It's annoying seeing *_templ.go and style.css be updated by themselves, which seems to happen more often than I would expect. If this is a bad idea for whatever reason, I can unignore them.

[joerdav]

I've seen a few different air+templ hot-reload approaches now and tried a couple, all with their own tradeoffs! I plan on documenting the best approach I find, hopefully with minimal config.

And on committing _templ.go files I prefer to commit them personally, the diffs don't bother me too much especially since GitHub is good at filtering out generated code. Another reason is that if you were publishing some templ components as a go module you would have to commit generated files, and it would seem odd to me to have different approaches for a component library and a web app.

[nathan-hello]

I'm back. I wanted to get rid of the half-baked air stuff. If someone can get air working, I'll take the pr on my repo. Also, I tried fixing the aforementioned issue with one of the React blurbs and couldn't figure it out.

I thought I had removed the mini project inside of docs/docs, but I guess not. Again, if there's some reason for them to exist I'd love to know.

@cugu for my sake in trying to troubleshoot the prism/goldmark stuff with this, could you explain the ideas around the goldmark config? I'm trying to parse how it goes from " ```ts " to whatever prism.js interprets. In doing so, it seems like the goldmark config has a bunch of stuff that I have no idea what it does.

[cugu]

Goldmark converts ```templ to <pre><code class="language-templ">.
Prism.js does syntax highlighting on those blocks.

For the purpose of the other goldmark extensions, their effects should be listed here: https://github.com/yuin/goldmark?tab=readme-ov-file#list-of-extensions