proposal: Config-less docs structure

[PuruVJ]

Problem

Currently any and all docs have to be specified in nav.js file. This is extra redundancy.

Solution

We get rid of nav.js. Split the documentation into sections with .md files being the page slugs, and meta.json for section title.

Structure:

- introduction
  - meta.json              <----- This is a json file with { title: "Introduction" } as content
  - overview.md.           <----- This is URL: `/docs/introduction/overview`
  - getting-started.md     <----- This is URL: `/docs/introduction/getting-started`
- deploying
  - meta.json
  - testnet.md
- unity
  - meta.json
  - part-1.md
  - part-2.md

This will require setting up redirects for the overview routes, (which is like a 10 line piece of code), but the advantage is that our URLs will become consistent. Currently some urls have 0, some have 1 slug, some have 2, some even have 3. This will make em all just 2 fixed slugs, which is easier to reason with.

How about title of a chapter?

This will be defined in the frontmatter:

---
title: Testnet
---

<<CONTENT>>

This lets us add future config right within the content(manual next or previous, tags, version separation, etc)

Prerequisites

Need the remix rewrite to become the prod site, as rewriting now will make it incompatible with the current site.

Final complete structure:

- 00-introduction        
  - 00-overview.md       
  - 10-getting-started.md
- 01-deploying
  - 00-testnet.md
- 02-unity-basic
  - 00-1.md
  - 10-2a-rust.md
  - 20-2a-c-sharp.md
  - 30-3.md
- 03-unity-advanced
  - 00-4.md
  - 10-5.md
- 04-modules
  - 00-overview.md
  - 10-rust-quickstart.md
  - 20-rust-reference.md
  - 30-c-sharp-quickstart.md
  - 40-c-sharp-reference.md
- 05-sdks
  - 00-typescript-quickstart.md
  - 01-typescript-reference.md
  - 10-rust-quickstart.md
  - 11-rust-reference.md
  - 20-python-quickstart.md
  - 21-python-reference.md
  - 30-c-sharp-quickstart.md
  - 31-c-sharp-reference.md
- 06-webassembly-abi
  - 00-overview.md
- 07-http
  - 00-overview.md
  - 10-identity.md
  - 20database.md
  - 30-energy.md
- 08-ws
  - 00-overview.md
- 09-data-format
  - 00-satn.md
  - 10-bsatn.md
- 10-sql
  - 00-overview.md

The numbers as prefixes are for ensuring the order of the navigation. The numbers are stripped altogether, and only used for filesystem sorting. Can be anything 2-digits. This lets the content authors to also take care of the pages order while authoring documents.

All directories get a meta.json to specify the category title.

Can we keep it variable-depth?

Instead of /modules/rust-quickstart, can we stay with /modules/rust/quickstart? We can, but then we'd have to rectify the depth artificially in the sidebar config too, which means we're back to configuration which is prone to breaking.

What about redirects?

Redirects will be done server-side in the new site, so the change will be instantaneous and will not have any flickering.

Redirects will look something along these lines:

const map = {
  'unity/part-1': 'unity/1'
}

redirect(map[url.pathname]);

[dylanh724]

• The nav.js automatically sets the "next" section: Since we already highlight which section you're on, you probably don't need it anyway:

• Another advantage this PR is to potentially have more than 1 nesting. There are some situations where an extra +1 nest would be nice (albeit more-rare).

• Finally, there are situations where a static "next" doesn't apply, resulting in inconsistent footers. For example, the next chapter may be module code that could fork into 1 section for Rust, 1 section for C#.

I like it.

EDIT: However, I do recall the entire docs architecture may be revamped soon? This could be a moot PR, if that's the case. For example, in the current state:

1. You can't locally host a preview of the result
2. You can't preview static /images that are stored on a completely different repo (spacetime-web)
3. ...Some other mentions that I couldn't recall

[PuruVJ]

However, I do recall the entire docs architecture may be revamped soon?

I wasn't aware of that 😅. I'll be on standby on this

[PuruVJ]

https://github.com/clockworklabs/spacetime-docs/pull/53 shows how much we need a consistent structure and automatic generation.