Publish comprehensive Substrate docsite before v1.0 release

[zlammerts-svg]

Motivation
As we approach the v1.0 release of Substrate, we need a dedicated, user-friendly documentation website to help onboard new users and showcase the project's capabilities. A centralized docsite is critical for adoption and will serve as the single source of truth for guides, architecture, and examples.

Proposed Solution
Create and publish a comprehensive docsite similar in structure and quality to the Agent Sandbox docsite.

The site should include:

• How-to Guides: Step-by-step instructions for installation, configuration, and common operations.

• Use Cases: Real-world scenarios and architectures where Substrate adds value.

• Demos: Interactive examples, videos, or copy-pasteable snippets demonstrating core features.

Open Questions / Blockers

Domain Name: We need to confirm if we have a registered domain we can use for this (e.g., something like substrate.dev, agent-substrate.io, or a subdomain if hosted under an existing umbrella). Tim Hockin (@thockin) can confirm if we have a domain ready.

Task List

• Confirm and provision the domain name.
• Choose a documentation framework (MkDocs, or Hugo etc) and scaffold the site.
• Write and migrate How-to content.
• Write and format Use Cases.
• Record or prepare Demos to embed in the site.
• Set up CI/CD for automated publishing (e.g., GitHub Pages).
• Final review of content and formatting.
• Go live.

[zlammerts-svg]

Eitan Yarmush (@EItanya) Raji (@Raji14) Tim Hockin (@thockin) Mofi Rahman (@moficodes) Benjamin Elder (@BenTheElder) We need to scope out the docsite for v1.0. Let's discuss the details here.

[stshrive]

Zheng Lammerts (@zlammerts-svg), do we have an idea of which docs are in scope for this or is that part of this exercise? A CI/CS for automated publishing of docs can't really be scoped out until that is known. Would site pages be hosted as a separate repo (short-term/long-term)?

[BenTheElder]

It should be a separate repo in the long term. If only to avoid issues with CI and permissions etc.

In the short term making repos is somewhat problematic, but longterm we should use a dedicated repo and something like GitHub pages + Hugo.

To start we need a landing page describing the project. Then we'll want to fill in docs and examples.

[moficodes]

I think a /site at root makes sense for now. Github pages works for custom domains as well. Do we have a design in mind? Many of the CNCF projects use Docsy including Agent Sandbox (although we changed the look and feel of that quite a bit to the point its no longer obvious that its docsy).

Do we have any designs in mind? Any preference of Hugo themes?

[moficodes]

My recommendation is Docsy and we can customize that to whatever design we want.

One more thing to consider is that do we keep the docs part of the main repo and make the hugo site make copies of them at build time? or do we make the website the source of documentation, in that way all docs get moved under /site or separate repo in the future. And substrate just links to it where applicable.

Making the docsite the source of truth makes it easier to build and test, at the cost of docs not living in the same folders where code is. Making the docsite do some copy at build time would mean all the markdown in the repo can stay where they are and copied during build. A little complexity for the docsite but means no other change in the repo is required.

My personal preference is making docsite the source of truth and linking any other markdown in the main repo to link to it. But happy to discuss.