Concepts overhaul

*Rewrite basic concepts down to 3 pages

*Add tooltips

*General overhaul of concepts

Co-authored with @2color

Author: ElPaisano

.github/styles/Vocab/ipfs-docs-vocab/accept.txt

@@ -43,6 +43,7 @@
 [Mm]ulticodec
 [Mm]ultiformats
 [Mm]ultihash
+[Mm]ulticast
 [Nn]amespace
 [Pp]reload
 [Pp]ub[Ss]ub
@@ -66,6 +67,7 @@ Browserify
 callouts?
 CAs?
 CDNs?
+CIDs
 Certbot
 CNAMEs?
 codec
@@ -136,6 +138,8 @@ Metamask
 Minty('s)?
 Mojitos
 multipage
+multihashes
+multihash
 Nagaraj
 Nakamoto('s)?
 Namebase
@@ -203,3 +207,14 @@ whitepaper
 WiFi
 WS
 ^WSS$
+youtube
+upgradeability
+wantlists
+requesters
+[Ss]neakernet
+Sneakernets
+upgradeability
+performant
+sneakernet
+Sneakernet
+Bitswap

docs/.vuepress/config.js

@@ -99,25 +99,33 @@ module.exports = {
           ],
           '/concepts/': [
             {
-              title: 'Basic Concepts',
+              title: 'Basics',
               sidebarDepth: 1,
               collapsable: true,
               children: [
                   '/concepts/what-is-ipfs',
+                  '/concepts/ipfs-solves',
                   '/concepts/how-ipfs-works',
-                  '/concepts/content-addressing',
+              ]
+            },
+            {
+              title: 'Ideas and theory',
+              sidebarDepth: 1,
+              collapsable: true,
+              children: [
                   '/concepts/hashing',
                   '/concepts/immutability',
                   '/concepts/persistence',
                   '/concepts/privacy-and-encryption',
-                  '/concepts/nodes'
+                  '/concepts/nodes',
               ]
             },
             {
-              title: 'Subsystems and Components',
+              title: 'Subsystems and components',
               sidebarDepth: 1,
               collapsable: true,
               children: [
+                '/concepts/content-addressing',
                 '/concepts/bitswap',
                 '/concepts/dht',
                 '/concepts/dnslink',
@@ -154,8 +162,8 @@ module.exports = {
                   'https://github.com/ipfs-examples/js-ipfs-examples/tree/master/examples/custom-ipfs-repo',
                   'Customize an IPFS repo'
                 ],
-                '/how-to/best-practices-for-ipfs-builders',
-                '/how-to/troubleshooting'
+                '/how-to/kubo-garbage-collection',
+                '/how-to/troubleshooting',   
               ]
             },
             {
@@ -169,7 +177,7 @@ module.exports = {
                 '/how-to/take-snapshot',
                 '/how-to/store-play-videos',
                 '/how-to/host-git-repo',
-                '/how-to/move-ipfs-installation/move-ipfs-installation'
+                '/how-to/move-ipfs-installation/move-ipfs-installation',
               ]
             },
             {
@@ -230,7 +238,15 @@ module.exports = {
               collapsable: true,
               children: [
                 '/how-to/mint-nfts-with-ipfs',
-                '/how-to/best-practices-for-nft-data'
+                '/how-to/best-practices-for-nft-data'         
+              ]
+            },
+            {
+              title: 'Privacy and Encryption',
+              sidebarDepth: 1,
+              collapsable: true,
+              children: [
+                ['/how-to/privacy-best-practices', 'Privacy and Encryption'], 
               ]
             }
           ],
@@ -342,6 +358,7 @@ module.exports = {
   plugins: [
     [require('./plugins/vuepress-plugin-speedcurve'), { id: SPEEDCURVE_ID }],
     '@vuepress/plugin-back-to-top',
+    ['@adamdehaven/vuepress-plugin-custom-tooltip'],
     [
       '@vuepress/google-analytics',
       {

docs/.vuepress/redirects

@@ -1,6 +1,6 @@
 /basics/desktop-app /how-to/desktop-app
-/basics/go/ /install/command-line
-/basics/go/command-line /how-to/kubo-basic-cli
+/basics/go/command-line-quick-start /how-to/command-line-quick-start
+/basics/concepts /concepts
 /basics/js/js-ipfs /install/js-ipfs
 /basics/ipfs-implementations /concepts/ipfs-implementations
 /community/chat /community

docs/README.md

@@ -13,8 +13,7 @@ While IPFS is a file system, it is _not_ a storage system. Instead, IPFS can be
 
 Check out these docs to get started with IPFS:
 
-- [What is IPFS?](concepts/what-is-ipfs.md#what-is-ipfs)
-- [Key concepts](concepts/README.md)
+- [Learn the basics](concepts/README.md#learn-the-basics)
 - [Case studies](concepts/README.md#examples-and-case-studies)
 - [How-to guides](how-to/README.md)
 - [API and CLI references](reference/README.md)
@@ -41,7 +40,7 @@ Protect yourself from single-point-of-failure risks and benefit from decentraliz
 
 Want to know more about the decentralized web (DWeb) and how it's changing the internet? These resources will give you a clearer understanding of the DWeb movement, and how it's improving the world:
 
-- [What is IPFS](concepts/what-is-ipfs.md)
+- [IPFS and the problems it solves](concepts/what-is-ipfs.md)
 - [Peer-to-peer sharing](concepts/dht.md)
 - [Content-addressed data](concepts/content-addressing.md)
 

docs/concepts/README.md

@@ -3,83 +3,84 @@ title: Concepts
 description: Get started on understanding the key ingredients in the decentralized web and how IPFS works.
 ---
 
-# IPFS concepts
+# Concepts
 
-New to IPFS or the distributed web? Here's where to get started on understanding the key ingredients in what makes IPFS work. Because IPFS is a system that hopes to change how we use the Internet, it comes with many new concepts! This section aims to get you up to speed quickly.
+Welcome to the Concepts section of the InterPlanetary File System (IPFS) docs. Here, you can:
 
-## Video overviews
-
-Want the basics in theater mode? Check out these helpful videos for an overview of how IPFS works with files and the overall data lifecycle in the d-web.
-
-@[youtube](Z5zNPwMDYGg)
+- Learn what IPFS is and isn't, the problems it solves, the different subsystems that it is comprised of and how each one works in [the 3-page Basic Concepts](#learn-the-basics).
+- Dive into ideas like hashing, immutability, persistence (and more) that underlie IPFS in [Ideas and theory](#ideas-and-theory)
+- Learn more about the subsystems that IPFS is comprised of in [Subsystems and components](#subsystems-and-components)
+- Get an [overview of IPFS implementations](../concepts/ipfs-implementations.md).
+- [Compare IPFS to other similar systems](../concepts/comparisons.md).
+- Get answers to common questions about IPFS in [the FAQ](../concepts/faq.md).
+- Reference [the glossary of terms used in the IPFS ecosystem](../concepts/glossary.md).
+- Read [academic papers written about IPFS, including the original IPFS whitepaper](../concepts/further-reading/academic-papers.md).
+- Get inspired with [IPFS usage ideas and examples](#examples-and-case-studies).
+- Learn about IPFS in theater mode with [these helpful videos](#video-overviews).
 
-- [Understanding how IPFS deals with files (IPFS Camp 2019)](https://youtu.be/Z5zNPwMDYGg)
-
-@[youtube](fLUq0RkiTBA)
+:::callout
+### Don't see what you're looking for?
 
-- [The lifecycle of data in the DWeb (IPFS Camp 2019)](https://youtu.be/fLUq0RkiTBA)
+We're adding more documentation all the time and making ongoing revisions to existing docs, but if you don't see what you need, please [file an issue](https://github.com/ipfs/ipfs-docs/issues/new?assignees=&labels=OKR+3%3A+Content+Improvement%2C+docs-ipfs&template=content-request.md&title=%5BCONTENT+REQUEST%5D+%28add+your+title+here%21%29) to let us know! We also recommend visiting the [IPFS forums](https://discuss.ipfs.tech/) for support and discussion with IPFS enthusiasts and experts worldwide.
+:::
 
-@[youtube](J-drqD2UebM)
+## Learn the basics
 
-- [IPFS: A Whiteboard Overview](https://www.youtube.com/watch?v=J-drqD2UebM)
+1. [What IPFS is and isn't](../concepts/what-is-ipfs.md)
+1. [IPFS and the problems it solves](../concepts/ipfs-solves.md)
+1. [How IPFS works](../concepts/how-ipfs-works.md)
 
-Check out ResNetLab on Tour for complete tutorials on IPFS and the Web 3.0 stack:
+## Ideas and theory
 
-- [ResNetLab on Tour 2021](https://research.protocol.ai/tutorials/resnetlab-on-tour/)
-
-## IPFS 101
+- [Cryptographic hashing](hashing.md)
+- [Immutability](immutability.md)
+- [Persistence, permanence and pinning](persistence.md)
+- [Privacy and encryption](privacy-and-encryption.md)
+- [Nodes](nodes.md)
 
-Get the basic concepts of IPFS in one place, including:
+## Subsystems and components
 
-- [What is IPFS?](what-is-ipfs.md)
-- [How IPFS works](how-ipfs-works.md)
-- [Glossary](glossary.md)
-- [FAQ](faq.md)
+- [Content Identifiers (CIDs)](content-addressing.md)
+- [Bitswap](bitswap.md)
+- [Distributed Hash Tables (DHTs)](dht.md)
+- [DNSLink](dnslink.md)
+- [File systems](file-systems.md)
+- [IPFS Gateway](ipfs-gateway.md)
+- [IPLD](ipld.md)
+- [IPNS](ipns.md)
+- [libp2p](libp2p.md)
+- [Merkle Directed Acyclic Graphs (DAGs)](merkle-dag.md)
 
 ## Examples and case studies
 
-Get inspired by usage ideas, explore examples of IPFS implemented in the wild, and dig deeper with case studies on applications and projects in which IPFS plays a crucial role.
-
 - [Usage ideas & examples](usage-ideas-examples.md)
-- [Case study: Arbol](case-study-arbol.md)
-- [Case study: Audius](case-study-audius.md)
-- [Case study: Fleek](case-study-fleek.md)
-- [Case study: LikeCoin](case-study-likecoin.md)
-- [Case study: Morpheus.Network](case-study-morpheus.md)
-- [Case study: Snapshot](case-study-snapshot.md)
+- [Case study: Arbol](../case-studies/arbol.md)
+- [Case study: Audius](../case-studies/audius.md)
+- [Case study: Fleek](../case-studies/fleek.md)
+- [Case study: LikeCoin](../case-studies/likecoin.md)
+- [Case study: Morpheus.Network](../case-studies/morpheus.md)
+- [Case study: Snapshot](../case-studies/snapshot.md)
 
-## Content-addressed storage
+## Video overviews
 
-Referring to files by their content, not their location, is one of the most powerful concepts within IPFS. Learn why with explainers on:
+<!-- markdown-link-check-disable -->
+@[youtube](Z5zNPwMDYGg)
 
-- [Content addressing](content-addressing.md)
-- [Cryptographic hashing](hashing.md)
-- [Immutability](immutability.md)
-- [Persistence, permanence and pinning](persistence.md)
+- [Understanding how IPFS deals with files (IPFS Camp 2019)](https://youtu.be/Z5zNPwMDYGg)
 
-## Peer-to-peer file sharing
+@[youtube](fLUq0RkiTBA)
 
-Sharing files between peers is incredibly powerful — and has many nuances! Learn about file-sharing paradigms and tools:
+- [The lifecycle of data in the DWeb (IPFS Camp 2019)](https://youtu.be/fLUq0RkiTBA)
 
-- [Distributed Hash Tables (DHTs)](dht.md)
-- [Merkle DAGs](merkle-dag.md)
-- [Bitswap](bitswap.md)
-- [IPLD](ipld.md)
-- [IPNS](ipns.md)
-- [libp2p](libp2p.md)
-- [File systems](file-systems.md)
+@[youtube](J-drqD2UebM)
 
-## Integrating IPFS and the existing Web
+- [IPFS: A Whiteboard Overview](https://www.youtube.com/watch?v=J-drqD2UebM)
+<!-- markdown-link-check-enable-->
+Check out ResNetLab on Tour for complete tutorials on IPFS and the Web 3.0 stack:
 
-IPFS aims to be the future of the internet, but it still needs to play well with today's Web. Here are some ways to do just that:
+- [ResNetLab on Tour 2021](https://research.protocol.ai/tutorials/resnetlab-on-tour/)
 
-- [IPFS Gateway](ipfs-gateway.md)
-- [DNSLink](dnslink.md)
 
 ## Further reading
 
 Want a more in-depth look into the decentralized web? Here are a few papers that are useful for understanding IPFS, whether it be understanding the IPFS spec itself or the background for the web, protocols, hashing, and so on. [Read the papers →](further-reading/academic-papers.md)
-
-## Don't see what you're looking for?
-
-We're adding more documentation all the time and making ongoing revisions to existing docs, but if you don't see what you need, please [file an issue](https://github.com/ipfs/ipfs-docs/issues/new?assignees=&labels=OKR+3%3A+Content+Improvement%2C+docs-ipfs&template=content-request.md&title=%5BCONTENT+REQUEST%5D+%28add+your+title+here%21%29) to let us know! We also recommend visiting the [IPFS forums](https://discuss.ipfs.tech/) for support and discussion with IPFS enthusiasts and experts worldwide.

docs/concepts/comparisons.md

@@ -1,11 +1,9 @@
 ---
-title: 'IPFS Comparisons'
+title: 'IPFS comparisons'
 description: Comparing IPFS to other solutions.
 ---
 
-# IPFS Comparisons
-
-## How is IPFS different from other solutions?
+# IPFS comparisons
 
 IPFS is a general-purpose file system that uses a distributed hash table (DHT) to route and transfer content-addressed data. This sets it apart from other solutions with a more specific focus or use of a specific data storage mechanism. For example: