[META] General structure, flow, & content enhancements

[salmad3]

Context

• Improve the overall content presentation and navigation of the docs.
• Adds sections and directories for current content.
• This PR will primarily include theme-level changes. Additional PRs will propose changes to populate and improve the various sections, as well as add/modify sub-sections where needed.
• This structure will be iterated on as we add content.

Original proposed structure with chapter/book approach:

 ┣ 1. Introduction
 ┃ ┣ 1.1. Network Basics
 ┃ ┃ ┣ 1.1.1. The Internet and the Permanent Web
 ┃ ┃ ┣ 1.1.2. Introduction to Computer Networks
 ┃ ┃ ┣ 1.1.3. Introduction to Distributed Computing
 ┃ ┃ ┣ 1.1.4. Introduction to Data Structures
 ┃ ┣ 1.2. libp2p
 ┃ ┃ ┣ 1.2.1 A Modular P2P Networking Stack
 ┣ 2. Core Components
 ┃ ┣ 2.0. Fundamentals
 ┃ ┃ ┣ 2.0.1. Overview
 ┃ ┃ ┣ 2.0.2. Addressing
 ┃ ┃ ┣ 2.0.3. Protocols
 ┃ ┃ ┣ ...
 ┃ ┃ ┣ ...
 ┃ ┃ ┣ 2.0.n. More
 ┃ ┣ 2.1. Transports
 ┃ ┃ ┣ 2.1.1. Overview
 ┃ ┃ ┣ 2.1.2. TCP
 ┃ ┃ ┣ 2.1.3. QUIC
 ┃ ┃ ┣ 2.1.4. WebSocket
 ┃ ┃ ┣ 2.1.5. WebTransport
 ┃ ┃ ┣ 2.1.6. WebRTC
 ┃ ┣ 2.2. Secure Communication
 ┃ ┃ ┣ 2.2.1. Overview
 ┃ ┃ ┣ 2.2.2. Noise
 ┃ ┃ ┣ 2.2.3. TLS
 ┃ ┣ 2.3. Stream Multiplexing
 ┃ ┃ ┣ 2.3.1. Overview
 ┃ ┃ ┣ 2.3.2. mplex
 ┃ ┃ ┣ 2.3.3. yamux
 ┃ ┣ 2.4. NAT Traversal
 ┃ ┃ ┣ 2.4.1. Overview
 ┃ ┃ ┣ 2.4.2. Circuit Relay
 ┃ ┃ ┣ 2.4.3. Hole Punching
 ┃ ┃ ┣ 2.4.4. AutoNAT
 ┃ ┃ ┣ 2.4.5. DCUtR
 ┃ ┣ 2.5. Discovery
 ┃ ┃ ┣ 2.5.1. Overview
 ┃ ┃ ┣ 2.5.2. mDNS
 ┃ ┃ ┣ 2.5.3. Random Walk
 ┃ ┃ ┣ 2.5.4. Rendezvous
 ┃ ┣ 2.6. Routing
 ┃ ┃ ┣ 2.6.1. Overview
 ┃ ┃ ┣ 2.6.2. Peer Identity
 ┃ ┃ ┣ 2.6.3. Peer Routing
 ┃ ┃ ┃ ┣ 2.6.3.1. DHT-based Peer Routing
 ┃ ┃ ┣ 2.6.4. Content Routing
 ┃ ┃ ┃ ┣ 2.6.4.1. DHT-based Peer Routing
 ┃ ┣ 2.7. Messaging
 ┃ ┃ ┣ 2.7.1. Overview
 ┃ ┃ ┣ 2.7.2. Publish/Subscribe
 ┃ ┣ 2.8. Data Exchange
 ┃ ┃ ┣ 2.8.1. Overview
 ┃ ┃ ┣ 2.8.2. Bitswap
 ┃ ┣ 2.9. Security Considerations
 ┃ ┃ ┣ 2.9.1. Overview
 ┃ ┣ 2.10. Miscellaneous
 ┃ ┃ ┣ 2.10.1. Glossary
 ┣ 3. Guides
 ┃ ┣ 3.1. Get Started
 ┃ ┃ ┣ 3.1.1. Install libp2p
 ┃ ┃ ┣ 3.1.2. Quick Start
 ┃ ┣ 3.2. Protocol Basics
 ┃ ┃ ┣ 3.2.1. Prerequisites
 ┃ ┃ ┣ 3.2.2. Transports
 ┃ ┃ ┣ 3.2.3. Secure Channels
 ┃ ┃ ┣ 3.2.4. Steam Muxers
 ┃ ┃ ┣ 3.2.5. Peer Discovery
 ┃ ┃ ┣ 3.2.6. NATs
 ┃ ┃ ┣ 3.2.7. Peer Routing
 ┃ ┃ ┣ 3.2.8. Content Routing
 ┃ ┃ ┣ 3.2.9. P2P Messaging
 ┃ ┃ ┣ 3.2.10. Data Exchange
 ┃ ┣ 3.3. Examples
 ┃ ┃ ┣ 3.3.1. Overview
 ┃ ┃ ┣ 3.3.2. Chat Application
 ┃ ┃ ┣ ...
 ┃ ┃ ┣ ...
 ┃ ┃ ┣ 3.3.n. Example
 ┣ 4. Reference
 ┃ ┣ 4.1. Overview
 ┃ ┣ ...
 ┃ ┣ ...
 ┃ ┣ 4.n. More
 ┣ 5. Community
 ┃ ┣ 4.1. Get Involved
 ┃ ┣ 4.2. How to Contribute

Current restructure: latest preview

Please view the latest Fleek preview here.

[netlify]

✅ Deploy Preview for libp2p-docs-mirror ready!

Name	Link
🔨 Latest commit	4c2b7fc
🔍 Latest deploy log	https://app.netlify.com/sites/libp2p-docs-mirror/deploys/6320007e9c468a000887969c
😎 Deploy Preview	https://deploy-preview-186--libp2p-docs-mirror.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[marten-seemann]

It would probably make sense to interchange WebTransprot and WebRTC:
┃ ┃ ┣ 2.1.4. WebSocket
┃ ┃ ┣ 2.1.5. WebTransport
┃ ┃ ┣ 2.1.6. WebRTC

Haven't looked at the rest of the structure yet, will do when this is not a draft any more.

[salmad3]

Tagged the team for their input when they have the chance for an initial review

[marten-seemann]

There's a lot of changed files in this PR, not sure what exactly to review here. The proposed structure from the PR description?

[salmad3]

@p-shahi @marten-seemann thanks again! Based on the feedback, I decided it's best to simplify the restructure approach here and work off of the current "portal" we have, where we can soon decide on how we'd like to "generally revamp" the libp2p site, docs, etc - I feel there is consensus to do so. We're preparing a proposal on different approaches we can take that I'll share next week.

For now, here are highlights of the recent changes:

• The changes categorize concepts based on components (but without chapter numbers) and create directories (or sections).
  • Uses index files to capture the overview/summary of the component, then lists a ToC for the specific components related to the general component on the index file (e.g. with Transports - there is a doc for dialing & listening, then for QUIC and WebTransport).
  • Added placeholders back for secure channels and stream muxer (these will be updated relatively soon).
  • The categories (or previously, chapters) that did not have content and acted as placeholders, I removed.
  • The categories with only "one main overview", are not a directories and are displayed as they originally were.
  • Glossary page is displayed as is
• Reference section added back.

  Would note @p-shahi that I had added a redirect when we moved DoS to "Core Components", so if we'd like to reconsider the visibility again, we can do it in this PR.

• Descriptions updated for all page. but they are not thought-through. This is something I'll update once we decide on the structure as it would be worth having a similar tone and follow a standard on how we refer to different parts of the docs (i.e. sections vs. categories. vs. directories vs. something else.)

  Hugo will autogenerate content summaries with a default summaryLength of 70, but renders as regular text [on purpose] (the ones we have right now aren't good because of this), so we are now using the "summary" property available in the front matter.

• Added additional visibility for specs to the footer under the GitHub reference.

[p-shahi]

Based on the feedback, I decided it's best to simplify the restructure approach here and work off of the current "portal" we have, where we can soon decide on how we'd like to "generally revamp" the libp2p site, docs, etc - I feel there is consensus to do so. We're preparing a proposal on different approaches we can take that I'll share next week.

Ok sounds good.

The changes categorize concepts based on components (but without chapter numbers) and create directories (or sections).

I do like book/chapter style organization. I found that Aleo organizes their docs similarly: https://developer.aleo.org/overview (without numbering.)

Uses index files to capture the overview/summary of the component, then lists a ToC for the specific components related to the general component on the index file (e.g. with Transports - there is a doc for dialing & listening, then for QUIC and WebTransport).
The categories with only "one main overview", are not a directories and are displayed as they originally were.

👍

Reference section added back.
Would note @p-shahi that I had added a redirect when we moved DoS to "Core Components", so if we'd like to reconsider the visibility again, we can do it in this PR.

Yes, let's promote DoS to be under Core Components in this PR.
I meant that we should also keep a DoS page (with a link to Core Components>DoS) under Reference only if there was no redirect. Since you had added a redirect, it can be removed from under Reference. Sorry if there was confusion from my end.

Descriptions updated for all page. but they are not thought-through. This is something I'll update once we decide on the structure as it would be worth having a similar tone and follow a standard on how we refer to different parts of the docs (i.e. sections vs. categories. vs. directories vs. something else.)

👍

[salmad3]

@p-shahi gotcha, now back under core components:)

[salmad3]

@marten-seemann these changes should make things more straight forward and great if you can provide a final review.

[salmad3]

Upon merging this, I'll open PRs for AutoNAT, Noise, TLS, and will update yamux, mplex.

Regarding QUIC:
We currently mention QUIC on the stream multiplexing article, and this PR now creates a subsection for QUIC under stream multiplexing as it does with the other protocols and core components, but perhaps this is not needed and QUIC should only be explained under transports. I was thinking to add an overview on QUIC's "native stream multiplexing" under stream multiplexing, but in doing so, that would push us to add QUIC under secure channels (which may overlap with the TLS piece). I am in favor of this latter approach, and future diagrams would be valuable.

[p-shahi]

If no qualms, let's merge this by tomorrow e.o.d.

I was thinking to add an overview on QUIC's "native stream multiplexing" under stream multiplexing, but in doing so, that would push us to add QUIC under secure channels (which may overlap with the TLS piece). I am in favor of this latter approach, and future diagrams would be valuable.

makes sense to me.

[salmad3]

checking here @marten-seemann for any qualms.

[salmad3]

🛳️?

[p-shahi]

🚢 it 🚀