Merge pull request #8 from ipfs/feat-migration-tweaks-2

Second round of migration tweaks

Author: jessicaschilling

docs/essentials/merkle-dags.md

@@ -4,23 +4,23 @@ title: Merkle DAGs
 
 # Merkle Distributed Acyclic Graphs (DAGs)
 
-A _Direct Acyclic Graph_ (DAG)is a type of graph in which edges have direction and cycles are not allowed. For example, a linked list like _A→B→C_ is an instance of a DAG where _A_ references _B_ and so on. We say that _B_ is _a child_ or _a descendant of A_, and that _node A has a link to B_. Conversely _A_ is a _parent of B_. We call nodes that are not children to any other node in the DAG _root nodes_.
+A _Direct Acyclic Graph_ (DAG) is a type of graph in which edges have direction and cycles are not allowed. For example, a linked list like _A→B→C_ is an instance of a DAG where _A_ references _B_ and so on. We say that _B_ is _a child_ or _a descendant of A_, and that _node A has a link to B_. Conversely _A_ is a _parent of B_. We call nodes that are not children to any other node in the DAG _root nodes_.
 
-## Merkle-DAGs in brief
+## Merkle DAGs in brief
 
-A Merkle-DAG is a DAG where each node has an identifier and this is the result of hashing the node’s contents — any opaque payload carried by the node and the list of identifiers of its children — using a cryptographic hash function like SHA256. This brings some important considerations:
+A Merkle DAG is a DAG where each node has an identifier and this is the result of hashing the node’s contents — any opaque payload carried by the node and the list of identifiers of its children — using a cryptographic hash function like SHA256. This brings some important considerations:
 
-- Merkle-DAGs can only be constructed from the leaves, that is, from nodes without children. Parents are added after children because the children’s identifiers must be computed in advance to be able to link them.
-- every node in a Merkle-DAG is the root of a (sub)Merkle-DAG itself, and this subgraph is _contained_ in the parent DAG.
-- Merkle-DAG nodes are _immutable_. Any change in a node would alter its identifier and thus affect all the ascendants in the DAG, essentially creating a different DAG. Take a look at [this helpful illustration using bananas](https://media.consensys.net/ever-wonder-how-merkle-trees-work-c2f8b7100ed3) from our friends at Consensys.
+- Merkle DAGs can only be constructed from the leaves, that is, from nodes without children. Parents are added after children because the children’s identifiers must be computed in advance to be able to link them.
+- every node in a Merkle DAG is the root of a (sub)Merkle DAG itself, and this subgraph is _contained_ in the parent DAG.
+- Merkle DAG nodes are _immutable_. Any change in a node would alter its identifier and thus affect all the ascendants in the DAG, essentially creating a different DAG. Take a look at [this helpful illustration using bananas](https://media.consensys.net/ever-wonder-how-merkle-trees-work-c2f8b7100ed3) from our friends at Consensys.
 
-Merkle-DAGs are similar to Merkle trees, but there are no balance requirements and every node can carry a payload. In DAGs, several branches can re-converge or, in other words, a node can have several parents.
+Merkle DAGs are similar to Merkle trees, but there are no balance requirements and every node can carry a payload. In DAGs, several branches can re-converge or, in other words, a node can have several parents.
 
-Identifying a data object (like a Merkle-DAG node) by the value of its hash is referred to as _content addressing_. Thus, we name the node identifier as [_Content Identifier_](/essentials/content-addressing/), or CID.
+Identifying a data object (like a Merkle DAG node) by the value of its hash is referred to as _content addressing_. Thus, we name the node identifier as [_Content Identifier_](/essentials/content-addressing/), or CID.
 
-For example, the previous linked list, assuming that the payload of each node is just the CID of its descendant, would be: _A=Hash(B)→B=Hash(C)→C=Hash(∅)_. The properties of the hash function ensure that no cycles can exist when creating Merkle-DAGs. (Note: Hash functions are one-way functions. Creating a cycle should then be impossibly difficult, unless some weakness is discovered and exploited.)
+For example, the previous linked list, assuming that the payload of each node is just the CID of its descendant, would be: _A=Hash(B)→B=Hash(C)→C=Hash(∅)_. The properties of the hash function ensure that no cycles can exist when creating Merkle DAGs. (Note: Hash functions are one-way functions. Creating a cycle should then be impossibly difficult, unless some weakness is discovered and exploited.)
 
-Merkle-DAGs are _self-verified_ structures. The CID of a node is univocally linked to the contents of its payload and those of all its descendants. Thus two nodes with the same CID univocally represent exactly the same DAG. This will be a key property to efficiently sync Merkle-CRDTs without having to copy the full DAG, as exploited by systems like IPFS. Merkle-DAGs are very widely used. Source control systems like git and others use them to efficiently store the repository history, in away that enables de-duplicating the objects and detecting conflicts between branches.
+Merkle DAGs are _self-verified_ structures. The CID of a node is univocally linked to the contents of its payload and those of all its descendants. Thus two nodes with the same CID univocally represent exactly the same DAG. This will be a key property to efficiently sync Merkle-CRDTs without having to copy the full DAG, as exploited by systems like IPFS. Merkle DAGs are very widely used. Source control systems like git and others use them to efficiently store the repository history, in away that enables de-duplicating the objects and detecting conflicts between branches.
 
 ## Further resources
 

docs/how-tos/address-ipfs-on-web.md

@@ -4,10 +4,6 @@ title: Address IPFS on the Web
 
 # Address IPFS on the Web
 
-::: warning
-This draft content ported from the legacy docs site may contain broken links and other errors. (Please remove this alert once content has been reviewed.)
-:::
-
 <!--
 Based on the existing spec at:
 https://github.com/ipfs/in-web-browsers/blob/2896b7a642011bc92493971232b146e04c9a889c/ADDRESSING.md
@@ -18,21 +14,21 @@ https://github.com/ipfs/in-web-browsers/issues/147
 
 This document is a guide to how to address IPFS content paths on the web.
 
-## HTTP Gateways
+## HTTP gateways
 
 Gateways are provided strictly for convenience: in other words, they help tools that speak HTTP but do not speak distributed protocols such as IPFS. They are the first stage of the upgrade path for the web.
 
-### Centralization Concerns
+### Centralization concerns
 
-HTTP gateways have worked well since 2015, but they come with a significant set of limitations related both to the centralized nature of HTTP and some of HTTP's semantics. Location-based addressing of a gateway depends on both DNS and HTTPS/TLS, which relies on a trust in [certificate authorities](https://en.wikipedia.org/wiki/Certificate_authority) (CA) and [public key infrastructure](https://en.wikipedia.org/wiki/Public_key_infrastructure) (PKI). In the long term, these issues should be mitigated by use of opportunistic protocol upgrade schemes.
+HTTP gateways have worked well since 2015, but they come with a significant set of limitations related both to the centralized nature of HTTP and some of HTTP's semantics. Location-based addressing of a gateway depends on both DNS and HTTPS/TLS, which relies on a trust in [certificate authorities](https://en.wikipedia.org/wiki/Certificate_authority) (CAs) and [public key infrastructure](https://en.wikipedia.org/wiki/Public_key_infrastructure) (PKI). In the long term, these issues should be mitigated by use of opportunistic protocol upgrade schemes.
 
-### Protocol Upgrade
+### Protocol upgrade
 
 Tools and browser extensions should detect IPFS content paths and resolve them directly over IPFS protocol. They should use HTTP gateway only as a fallback when no native implementation is available in order to ensure a smooth, backward-compatible transition.
 
-### Gateway Types
+### Gateway types
 
-#### Path Gateway
+#### Path gateway
 
 In the most basic scheme, a URL path used for content addressing is effectively a resource name without a canonical location. The HTTP server provides the location part, which makes it possible for browsers to interpret an IPFS content path as relative to the current server and just work without a need for any conversion:
 
@@ -53,7 +49,7 @@ https://ipfs.io/ipfs/QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX/wiki/Mars.ht
 https://ipfs.io/ipns/tr.wikipedia-on-ipfs.org/wiki/Anasayfa.html
 ```
 
-#### Subdomain Gateway
+#### Subdomain gateway
 
 When [origin-based security](https://en.wikipedia.org/wiki/Same-origin_policy) perimeter is needed, [CIDv1](https://github.com/ipld/cid#cidv1) in Base32 ([RFC4648](https://tools.ietf.org/html/rfc4648#section-6), no padding) should be used in the subdomain:
 
@@ -68,13 +64,13 @@ Example:
   Right now, this type of gateway requires additional configuration (<a href="https://github.com/ipfs/infra/issues/81#issuecomment-461045160" target="_blank">example for Nginx&nbsp;<i class="fas fa-external-link-square-alt fa-sm"></i></a>); however, there is ongoing work to <a href="https://github.com/ipfs/go-ipfs/issues/5982" target="_blank">add native support in the IPFS daemon&nbsp;<i class="fas fa-external-link-square-alt fa-sm"></i></a>.
 </aside>
 
-#### DNSLink Gateway
+#### DNSLink gateway
 
 The gateway provided by the IPFS daemon understands the `Host` header present in HTTP requests, and will check if [DNSLink](/guides/concepts/dnslink) exists for a specified [domain name](https://en.wikipedia.org/wiki/Fully_qualified_domain_name).
 If DNSLink is present, the gateway will return content from a path resolved via DNS TXT record.
 This type of gateway provides full [origin isolation](https://en.wikipedia.org/wiki/Same-origin_policy).
 
-Example: https://docs.ipfs.io (this website)
+Example: [https://docs.ipfs.io](https://docs.ipfs.io) (this website)
 
 For a more complete DNSLink guide, including tutorials, usage examples and FAQs, check out [dnslink.io](https://dnslink.io).
 
@@ -107,24 +103,24 @@ ipfs://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq/wiki/Vincent_
 
 ---
 
-## References
+## Further resources
 
-### Technical Specification for Implementers
+### Technical specification for implementers
 
 The best and most up-to-date source of truth about IPFS addressing can be found in [the IPFS in-web-browsers repo](https://github.com/ipfs/in-web-browsers/blob/master/ADDRESSING.md).
 
-### Background on Address Scheme Discussions
+### Background on address scheme discussions
 
 Discussions around IPFS addressing have been going on since @jbenet published the [IPFS whitepaper](https://ipfs.io/ipfs/QmR7GSQM93Cx5eAg6a6yRzNde1FQv7uL6X1o4k7zrJa3LX/ipfs.draft3.pdf), with a number of other approaches being proposed. This long-standing design discussion includes many lengthy GitHub issue threads, but a good summary can be found in [this PR&nbsp;<i class="fas fa-external-link-square-alt fa-sm"></i></a>](https://github.com/ipfs/specs/pull/152).
 
-### Companion Browser Extension
+### IPFS Companion
 
 [IPFS Companion](https://github.com/ipfs-shipyard/ipfs-companion#ipfs-companion) is a
 browser extension that simplifies access to IPFS resources.
 
 It provides support for native URLs and will automatically redirect IPFS gateway requests to your local daemon so that you are not relying on, or trusting, remote gateways.
 
-### Future: Shared Dweb Namespace
+### Future: Shared dweb namespace
 
 The distributed web community is exploring the idea of a shared `dweb` namespace to remove the complexity of addressing IPFS and other content-addressed protocols. Currently investigated approaches include:
 

docs/how-tos/browser-tools-frameworks.md

@@ -2,13 +2,9 @@
 title: Use browser tools & frameworks
 ---
 
-# Browser implementation tools and frameworks
+# Using browser implementation tools and frameworks
 
-::: warning
-This draft content ported from the legacy docs site may contain broken links and other errors. (Please remove this alert once content has been reviewed.)
-:::
-
-Want to learn how to use IPFS combination with your favorite framework or browser implementation tool? See below for some common examples, including hints and boilerplate code. Don't see your framework or tool of choice here? Let us know by [filing an issue](https://github.com/ipfs/docs/issues/new?assignees=&labels=OKR+3%3A+Content+Improvement%2C+docs-ipfs&template=content-request.md&title=%5BCONTENT+REQUEST%5D+%20Browser%20Implementation%20Tools%20and%20Frameworks) in the IPFS docs GitHub repo.
+Want to learn how to use IPFS in combination with your favorite framework or browser implementation tool? See below for some common examples, including hints and boilerplate code. Don't see your framework or tool of choice here? Let us know by [filing an issue](https://github.com/ipfs/docs/issues/new?assignees=&labels=OKR+3%3A+Content+Improvement%2C+docs-ipfs&template=content-request.md&title=%5BCONTENT+REQUEST%5D+%20Browser%20Implementation%20Tools%20and%20Frameworks) in the IPFS docs GitHub repo.
 
 ## Browserify
 

docs/how-tos/command-line-quick-start.md

@@ -4,23 +4,15 @@ title: Command-line quick start
 
 # Command-line quick start
 
-::: warning
-This draft content ported from the legacy docs site may contain broken links and other errors. (Please remove this alert once content has been reviewed.)
-:::
-
 ## Install IPFS
 
-If you haven’t done so already, your first step is to **install IPFS**! Most people prefer to install a prebuilt package, which you can do on the [IPFS distributions page](https://dist.ipfs.io/#go-ipfs) by clicking “Install go-ipfs” (our reference implementation written in Go) and then following the instructions for [installing from a prebuilt package](../install/#installing-from-a-prebuilt-package).
-
-<a class="button button-primary" href="https://dist.ipfs.io/#go-ipfs" role="button">
-  Download IPFS for your platform &nbsp;&nbsp;<i class="fa fa-download" aria-hidden="true"></i>
-</a>
+If you haven’t done so already, your first step is to **install IPFS**! Most people prefer to install a prebuilt package, which you can do on the [IPFS distributions page](https://dist.ipfs.io/#go-ipfs) by clicking “Install go-ipfs” (our reference implementation written in Go) and then following the instructions for [installing from a prebuilt package](/install/).
 
-<aside class="alert alert-info">
-  Don’t want to use the command line right now? You can give the desktop-app implementation of IPFS a go! <a href="https://github.com/ipfs-shipyard/ipfs-desktop">Get started with IPFS Desktop here <i class="fas fa-external-link-square-alt fa-sm"></i></a>
-</aside>
+::: tip
+Don’t want to use the command line right now? Give the desktop-app implementation of IPFS a try. <a href="https://github.com/ipfs-shipyard/ipfs-desktop">Get started with IPFS Desktop here <i class="fas fa-external-link-square-alt fa-sm"></i></a>
+:::
 
-For more install options, such as building from source, and toubleshooting tips, visit our [install guide]{guides/guides/install.md). If you have any questions or get stuck, feel free to ask for help in [the Help section of the IPFS forums](https://discuss.ipfs.io/c/help) or in [#ipfs on chat.freenode.net](irc://chat.freenode.net/%23ipfs).
+For more install options, such as building from source, and toubleshooting tips, visit our [install guide](/install). If you have any questions or get stuck, feel free to ask for help in [the Help section of the IPFS forums](https://discuss.ipfs.io/c/help) or in [#ipfs on chat.freenode.net](irc://chat.freenode.net/%23ipfs).
 
 ## Initialize the repository
 
@@ -94,7 +86,7 @@ You can explore other objects in the repository. In particular, the `quick-start
 ipfs cat /ipfs/QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG/quick-start
 ```
 
-## Taking your Node Online
+## Take your node online
 
 Once you're ready to join your node to the public network, run the ipfs daemon in another terminal and wait for all three lines below to appear to know that your node is ready:
 
@@ -156,7 +148,7 @@ I <3 IPFS -<your username>
 
 By default, your gateway is not exposed to the world, it only works locally.
 
-## Web Console
+## Web console
 
 We also have a web console you can use to check the state of your node.
 In your favorite web browser, open:
@@ -167,21 +159,17 @@ This should bring up a console like this:
 
 ![Web console connection view](https://docs.ipfs.io/introduction/assets/webui-connection.png)
 
-## Companion Browser Extension
+## IPFS Companion
 
 While we are at it, [IPFS Companion](https://github.com/ipfs-shipyard/ipfs-companion#ipfs-companion) is a
 browser extension that simplifies access to IPFS resources and adds support for
 the IPFS protocol.
 
-<div class="alert alert-info">
-It will automatically redirect IPFS gateway requests to
-your local daemon so that you are not relying on, or trusting, remote gateways.
-</div>
+It will automatically redirect IPFS gateway requests to your local daemon so that you are not relying on, or trusting, remote gateways.
 
-It runs in Firefox (Desktop and Android)
-and various Chromium-based browsers such as Google Chrome or Brave.
-Check [its features](https://github.com/ipfs-shipyard/ipfs-companion#features) and [**install it**](https://github.com/ipfs-shipyard/ipfs-companion#install) today!
+It runs in Firefox (desktop and Android) and various Chromium-based browsers such as Google Chrome or [Brave](https://brave.com).
+[Check out its features](https://github.com/ipfs-shipyard/ipfs-companion#features) and install it today!
 
-| [Firefox](https://www.mozilla.org/firefox/new/) / [Firefox for Android](https://play.google.com/store/apps/details?id=org.mozilla.firefox)                       | [Chrome](https://www.google.com/chrome/) / [Brave](https://brave.com/)                                                                                                                   |
-| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [![Install From Firefox Add-ons](https://docs.ipfs.io/introduction/assets/get-the-firefox-add-on.png)](https://addons.mozilla.org/firefox/addon/ipfs-companion/) | [![Install from Chrome Store](https://docs.ipfs.io/introduction/assets/chrome-web-store.png)](https://chrome.google.com/webstore/detail/ipfs-companion/nibjojkomfdiaoajekhjakgkdhaomnch) |
+- [Direct download](https://github.com/ipfs-shipyard/ipfs-companion#install)
+- [Install from Firefox Add-ons](https://addons.mozilla.org/firefox/addon/ipfs-companion/)
+- [Install from Chrome Store](https://chrome.google.com/webstore/detail/ipfs-companion/nibjojkomfdiaoajekhjakgkdhaomnch)

docs/how-tos/configure-node.md

@@ -4,10 +4,6 @@ title: Configure a node
 
 # Configure an IPFS node
 
-::: warning
-This draft content ported from the legacy docs site may contain broken links and other errors. (Please remove this alert once content has been reviewed.)
-:::
-
 IPFS is configured through a json formatted text file, located by default at
 `~/.ipfs/config`.