Merge pull request #1490 from ipfs/publish-guide

Publish with IPFS using a pinning service guide

Author: 2color

docs/.vuepress/config.js

@@ -4,6 +4,16 @@ const DEPLOY_DOMAIN = 'https://docs.ipfs.tech'
 const SPEEDCURVE_ID = process.env.SPEEDCURVE_ID || ''
 const pageSuffix = '/'
 
+const installMenuChildren = [
+  ['/install/command-line','IPFS Kubo for Go'],
+  ['/install/run-ipfs-inside-docker', 'IPFS Kubo in Docker'],
+  ['/install/js-ipfs','IPFS for JavaScript'],
+  ['https://iroh.computer/docs/install/', "IPFS Iroh for Rust"],
+  ['/install/ipfs-desktop', 'IPFS Desktop App'],
+  ['/install/ipfs-companion', 'IPFS Companion Browser Extension'],
+  ['/install/server-infrastructure', 'IPFS Cluster']
+]
+
 module.exports = {
   base: '/',
   head: require('./head'),
@@ -82,20 +92,39 @@ module.exports = {
         sidebar: {
           '/install/':  [
             ['/concepts/what-is-ipfs','Basic Concepts'],
+            {
+              title: 'Quickstart',
+              sidebarDepth: 1,
+              collapsable: false,
+              children: [
+                ['/quickstart/publish','Publish with IPFS'],
+                ['/quickstart/retrieve','Retrieve with IPFS'],
+              ]
+            },
             {
               title: 'Install',
               sidebarDepth: 1,
               collapsable: false,
+              children: installMenuChildren
+            },
+          ],
+          '/quickstart/':  [
+            ['/concepts/what-is-ipfs','Basic Concepts'],
+            {
+              title: 'Quickstart',
+              sidebarDepth: 1,
+              collapsable: false,
               children: [
-                ['/install/command-line','IPFS Kubo for Go'],
-                ['/install/run-ipfs-inside-docker', 'IPFS Kubo in Docker'],
-                ['/install/js-ipfs','IPFS for JavaScript'],
-                ['https://iroh.computer/docs/install/', "IPFS Iroh for Rust"],
-                ['/install/ipfs-desktop', 'IPFS Desktop App'],
-                ['/install/ipfs-companion', 'IPFS Companion Browser Extension'],
-                ['/install/server-infrastructure', 'IPFS Cluster']
+                ['/quickstart/publish','Publish with IPFS'],
+                ['/quickstart/retrieve','Retrieve with IPFS'],
               ]
             },
+            {
+              title: 'Install',
+              sidebarDepth: 1,
+              collapsable: false,
+              children: installMenuChildren
+            },
           ],
           '/concepts/': [
             {
@@ -113,6 +142,7 @@ module.exports = {
               sidebarDepth: 1,
               collapsable: true,
               children: [
+                  '/concepts/lifecycle',
                   '/concepts/hashing',
                   '/concepts/immutability',
                   '/concepts/persistence',

docs/.vuepress/public/images/welcome-to-IPFS.jpg

@@ -5,7 +5,7 @@ description: Learn about how content addressing works and how content identifier
 
 # Content Identifiers (CIDs)
 
-As described in [IPFS and the problems it solves](../concepts/what-is-ipfs.md), IPFS is a modular suite of protocols purpose built for the organization and movement of <VueCustomTooltip label="A way to address data by its hash rather than its location (IPs)." underlined multiline>content-addressed data</VueCustomTooltip>. In this guide, you'll learn more about the fundamentals of content-addressing in IPFS and how IPFS uses Content Identifiers (CIDs) to handle content-addressed data.
+As described in [IPFS and the problems it solves](../concepts/what-is-ipfs.md), IPFS is a modular suite of protocols purpose built for the organization and transfer of <VueCustomTooltip label="A way to address data by its hash rather than its location (IPs)." underlined multiline>content-addressed data</VueCustomTooltip>. In this guide, you'll learn more about the fundamentals of content-addressing in IPFS and how IPFS uses Content Identifiers (CIDs) to handle content-addressed data.
 
 ## What is a CID?
 
@@ -33,7 +33,7 @@ CIDs contain the hash and the codec of the data. A CID can be represented in str
 While a data block's CID is constructed using the cryptographic hash of the data block, a CID contains additional information (described above) that the hash does not. For further information, see [CIDs are not file hashes](#cids-are-not-file-hashes) below.
 :::
 
-For a break-down of an actual CID, see [this example with the IPFS CID inspector](https://cid.ipfs.tech/#QmcRD4wkPPi6dig81r5sLj9Zm1gDCL4zgpEj9CfuRrGbzF).
+For a break-down of an actual CID, see [this example with the IPFS CID inspector](https://cid.ipfs.tech/#bafybeigrf2dwtpjkiovnigysyto3d55opf6qkdikx6d65onrqnfzwgdkfa).
 
 ## CIDs are not file hashes
 

docs/concepts/content-addressing.md

@@ -0,0 +1,50 @@
+---
+title: The lifecycle of data in IPFS
+description: Learn about the lifecycle of data in IPFS.
+---
+
+# The lifecycle of data in IPFS
+
+- [1. Content-addressable representation](#1-content-addressable-representation)
+- [2. Pinning](#2-pinning)
+- [3. Retrieval](#3-retrieval)
+- [4. Deleting](#4-deleting)
+- [Learn more](#learn-more)
+
+## 1. Content-addressable representation
+
+The file is transformed into a content-addressable representation using a CID. The basic idea is that this representation makes files and directories **content-addressable** via CIDs by chunking files into smaller blocks, calculating their hashes, and constructing a [Merkle DAG](./merkle-dag.md).
+
+## 2. Pinning
+
+In this stage, the blocks of the CID are saved on an IPFS node (or pinning service) and made retrievable to the network. Simply saving the CID on the node does not mean the CID is retrievable, so pinning must be used. Pinning allows the node to advertise that it has the CID, and provide it to the network.
+
+- **Advertising:** In this step, a CID is made discoverable to the IPFS network by advertising a record linking the CID and the server's IP address to the [DHT](./dht.md). Advertising is a continuous process that repeats typically every 12 hours. The term **publishing** is also commonly used to refer to this step.
+
+- **Providing:** The content-addressable representation of the CID is persisted on one of web3.storage's IPFS nodes (servers running an IPFS node) and made publicly available to the IPFS network.
+
+## 3. Retrieval
+
+In this stage, an IPFS node fetches the blocks of the CID and constructs the Merkle DAG. This usually involves several steps:
+
+- **Content routing:** The IPFS node finds other IPFS nodes providing the CIDs you are requesting. Content routing is facilitated by either the [DHT](./dht.md), asking already connected peers over [Bitswap](./bitswap.md), or making an HTTP call to a [delegated routing](https://github.com/ipfs/specs/blob/main/IPIP/0337-delegated-routing-http-api.md) server like the [network indexer](https://cid.contact/). The term **content discovery** is also commonly used to refer to this step.
+
+- **Block fetching:** An IPFS node fetches the blocks of the Merkle DAG (of the file or folder) from providers.
+
+- **Verification:** The IPFS node verifies the blocks fetched by hashing them and ensuring that the resulting hash is correct. Note that this type of retrieval is _trustless_; that is, blocks can come from any node in the network.
+
+- **Local access:** Once all blocks are present, the Merkle DAG can be constructed, making the file or directory underlying the CID successfully replicated and accessible.
+
+## 4. Deleting
+
+At this point, the blocks associated with a CID are deleted from a node. **Deletion is always a local operation**. If a CID has been replicated to other nodes, it will continue to be available on the IPFS network.
+
+:::callout
+Once the CID is replicated by another node, it is typically advertised to DHT by default, even if it isn't explicitly pinned.
+:::
+
+## Learn more
+
+Learn more about the lifecycle of data in IPFS in the following video:
+
+@[youtube](iaVXRPsRCUc)

docs/concepts/lifecycle.md

@@ -5,7 +5,11 @@ description: There are several different ways you can install and interact with
 
 # Get Started
 
-IPFS is a collection of protocols, packages, and specifications that allow computers to send and receive data. Because of this, users can pick and choose which packages to install when using IPFS. And like shoe sizes, there is no _one-size-fits-all_ solution. A developer building network applications will install a different set of tools than someone who wants to store files on IPFS. Pick the one that best suits what you're here to do.
+IPFS is a collection of protocols, packages, and specifications that allow computers to send and receive data. Because of this, users can interact with and use IPFS in many different ways. A developer building network applications will use a different set of tools to interact with IPFS than than someone who wants to store files on IPFS. Pick the one that best suits what you're here to do.
+
+## Publish files with a pinning service
+
+Do you want to quickly and easily publish content with IPFS without complex tools? See the [Publish with IPFS quickstart](../quickstart/publish.md), where you'll learn how to use pinning services to pin files to the IPFS network.
 
 ## IPFS Desktop