Phase 2 - tuning up our docs and docs website

[mrspence]

Hey guys! Quick update for you all.

In the background I've been quietly preparing the outline for our documentation site, and it's now at a phase ready for everyone's eyes and hands on it, before we prepare for going live.

Check it out here: https://docs.nanocollective.org
GitHub Repo: https://github.com/Nano-Collective/docs

What's there already

• A central docs hub for all our projects (Nanocoder, Nanotune, get-md, json-up, ...)
• Versioned docs pulled straight from each repo's docs/ folder on tagged releases - so anyone who can write markdown can now help write our docs
• Project and version selectors in the sidebar
• Full-text search with project filtering
• Dark mode (obviously 😉)
• Animated hero on the homepage
• Static site deploy
• Built on Nextra / Next.js, with ShadCN UI components available for future expansion

What we need next

Beyond writing docs, there's a bunch of stuff that needs attention; I see these becoming issues on the docs repo:

Content

• Sidebar and page meta. Right now, page titles are auto-generated from filenames and pages show up in whatever order they fancy. We need either YAML frontmatter (title, description, order, etc.) on repo markdown files or _meta.json files to control how pages are titled, ordered, and grouped in the sidebar. This also unlocks proper SEO.

• Nested folders. If your docs have subfolders (like Providers/Anthropic.md), they should nest properly in the sidebar.

• Mobile needs love, especially the header!

Homepage

• Projects vs libs. Nanocoder and Nanotune are full-blown projects. get-md and json-up are libs. Our homepage treats them all the same right now... but we want a layout that gives projects the spotlight they deserve... visuals/screenshots perhaps!

• Branding. We could bring in a subtler version of our main site's hero (nanocollective.org) to tie the docs site back to the mothership visually.

SEO and discoverability

• We need sitemap, robots.txt, OpenGraph tags... so we're not invisible to search engines.

Search

• Search is there and has basic project categorisation, but there's room to make it more reliable and more useful.

Polish

• Custom 404 page.

• "Edit this page" links pointing to the right files and repos.

• My least favourite: the sidebar currently relies on raw DOM manipulation. This has been a bit of a pain point with Nextra and raises some questions

Getting into it

So with CI and infrastructure is in place, the floor is open for everyone to weigh in! We can start tuning this up.

Have a poke around and drop any thoughts below 👌

[mrspence]

I suggest we get to creating sub-issues once we're ready!