Docs Formatting & Language

docs/address.md

@@ -1,15 +1,7 @@
----
-title: Address
-description: A simple interface to generate and validate a bitcoin address.
----
-# Address
-
-## Description
-
+# Bitcoin Address
 Represents a bitcoin address. Addresses are the most popular way to make bitcoin transactions. See [the official Bitcoin Wiki](https://en.bitcoin.it/wiki/Address) for technical background information.
 
 ## Instantiate an Address
-
 To be able to receive bitcoins an address is needed, but in order to spend them a private key is necessary. Please take a look at the [`PrivateKey`](privatekey.md) docs for more information about exporting and saving a key.  
 
 ```javascript
@@ -42,7 +34,6 @@ var p2shAddress = new Address([publicKey1, publicKey2, publicKey3], 2);
 ```
 
 ## Validating an Address
-
 The main use that we expect you'll have for the `Address` class in Bitcore is validating that an address is a valid one, what type of address it is (you may be interested on knowing if the address is a simple "pay to public key hash" address or a "pay to script hash" address) and what network does the address belong to.
 
 The code to do these validations looks like this:

docs/block.md

@@ -1,12 +1,5 @@
----
-title: Block
-description: A simple interface to parse and validate a bitcoin blocks.
----
-# Block
-
-## Description
-
-A Block instance represents the information of a block in the bitcoin network. Given a hexadecimal string representation of the serialization of a block with its transactions, you can instantiate a Block instance. Methods are provided to calculate and check the merkle root hash (if enough data is provided), but transactions won't necessarily be valid spends, and this class won't validate them. A binary representation as a `Buffer` instance is also valid input for a Block's constructor. 
+# Bitcoin Block
+A Block instance represents the information of a block in the bitcoin network. Given a hexadecimal string representation of the serialization of a block with its transactions, you can instantiate a Block instance. Methods are provided to calculate and check the merkle root hash (if enough data is provided), but transactions won't necessarily be valid spends, and this class won't validate them. A binary representation as a `Buffer` instance is also valid input for a Block's constructor.
 
 ```javascript
 // instantiate a new block instance
@@ -18,14 +11,12 @@ assert(block.validMerkleRoot());
 // blocks have several properties
 assert(block.header); // an instance of block header, more info below
 assert(block.transactions); // an array of transactions, more info below
-
 ```
 
 For detailed technical information about a block please visit [Blocks](https://en.bitcoin.it/wiki/Blocks#Block_structure) on the Bitcoin Wiki.
 
 ## Block Header
-
-Each instance of Block has a BlockHeader *(which can be instantiated separately)*. The header has validation methods, to verify that the block.
+Each instance of Block has a BlockHeader _(which can be instantiated separately)_. The header has validation methods, to verify that the block.
 
 ```javascript
 // will verify that the nonce demonstrates enough proof of work
@@ -41,17 +32,15 @@ assert(block.header.merkleRoot);
 assert(block.header.time);
 assert(block.header.bits);
 assert(block.header.nonce);
-
 ```
+
 For more information about the specific properties of a block header please visit the [Block hashing algorithm](https://en.bitcoin.it/wiki/Block_hashing_algorithm) page on the Bitcoin Wiki.
 
 ## Transactions
-
 The set of transactions in a block is an array of instances of [Transaction](transaction.md) and can be explored by iterating on the block's `transactions` member.
 
 ```javascript
 for (var i in block.transactions) {
   var transaction = block.transactions[i];
 }
 ```
-

docs/browser.md

@@ -1,14 +1,7 @@
----
-title: Browser Builds
-description: Guide to using and writing modules and optimizing browser bundles.
----
-
 # Browser Builds
-
 Bitcore and most official submodules work in the browser, thanks to [browserify](http://browserify.org/) (some modules are not fully compatible with web browsers).
 
-The easiest and recommended way to use them, is via [Bower](http://bower.io/), a browser package manager, and get the release bundles.
-For example, when building an app that uses `bitcore` and `bitcore-ecies`, you do:
+The easiest and recommended way to use them, is via [Bower](http://bower.io/), a browser package manager, and get the release bundles. For example, when building an app that uses `bitcore` and `bitcore-ecies`, you do:
 
 ```sh
 bower install bitcore
@@ -28,9 +21,11 @@ You can also use a `bower.json` file to store the dependencies of your project:
   }
 }
 ```
+
 and run `bower install` to install the dependencies.
 
 After this, you can include the bundled release versions in your HTML file:
+
 ```html
 <!DOCTYPE html>
 <html lang="en">
@@ -55,28 +50,26 @@ After this, you can include the bundled release versions in your HTML file:
 ```
 
 ## Building Custom Bundles
+If you want to use a specific version of a module, instead of a release version (not recommended), you must run browserify yourself.  You can get a minified browser bundle by running the following on the project root folder.
 
-If you want to use a specific version of a module, instead of a release version (not recommended), you must run browserify yourself. 
-You can get a minified browser bundle by running the following on the project root folder.
 ```sh
 browserify --require ./index.js:bitcore | uglifyjs > bitcore.min.js
 ```
+
 (for bitcore)
 
 ```sh
 browserify --require ./index.js:bitcore-ecies --external bitcore | uglifyjs > bitcore-ecies.min.js
 ```
-(for a bitcore module, `bitcore-ecies` in the example)
 
+(for a bitcore module, `bitcore-ecies` in the example)
 
 ## Development of Modules
-
-*Note:* You probably don't want to use this method, but `bitcore-build`, as explained above. This is left here as documentation on what happens under the hood with `bitcore-build`.
+_Note:_ You probably don't want to use this method, but `bitcore-build`, as explained above. This is left here as documentation on what happens under the hood with `bitcore-build`.
 
 When developing a module that will depend on Bitcore, it's recommended to exclude Bitcore in the distributed browser bundle when using browserify and to use the `--external bitcore` parameter. It will produce a smaller browser bundle, as it will only include the JavaScript that is nessessary, and will depend on the Bitcore browser build which is better for distribution.
 
 ### Building the Bundle Manually
-
 **Step 1**: Require Bitcore
 
 Here we require Bitcore and define the namespace (`index.js`):

docs/crypto.md

@@ -1,29 +1,17 @@
----
-title: Crypto
-description: Primitives and tools to deal with bitcoin cryptography.
----
-# Crypto
-
-## Description
-
+# Bitcoin Crypto
 The cryptographic primitives (ECDSA and HMAC) implementations in this package have been reviewed by the BitPay engineering team. More audits and reviews are welcomed.
 
 ## Random
-
 The `bitcore.crypto.Random` namespace contains a single function, named `getRandomBuffer(size)` that returns a `Buffer` instance with random bytes. It may not work depending on the engine that bitcore is running on (doesn't work with IE versions lesser than 11).
 
 ## BN
-
 The `bitcore.Crypto.BN` class contains a wrapper around [bn.js](https://github.com/indutny/bn.js), the bignum library used internally in bitcore.
 
 ## Point
-
 The `bitcore.Crypto.Point` class contains a wrapper around the class Point of [elliptic.js](https://github.com/indutny/elliptic), the elliptic curve library used internally in bitcore.
 
 ## Hash
-
 The `bitcore.Crypto.Hash` namespace contains a set of hashes and utilities. These are either the native `crypto` hash functions from `node.js` or their respective browser shims as provided by the `browserify` library.
 
 ## ECDSA
-
 `bitcore.Crypto.ECDSA` contains a pure JavaScript implementation of the elliptic curve DSA signature scheme based on [elliptic.js](https://github.com/indutny/elliptic).

docs/encoding.md

@@ -1,17 +1,8 @@
----
-title: Encoding
-description: Utilities for encoding information in bitcoin standard formats.
----
 # Encoding
-
-## Description
-
 The `bitcore.Encoding` namespace contains utilities for encoding information in common formats in the bitcoin ecosystem.
 
 ## Base58 & Base58Check
-
 Two classes are provided: `Base58` and `Base58Check`. The first one merely encodes/decodes a set of bytes in base58 format. The second one will also take the double `sha256` hash of the information and append the last 4 bytes of the hash as a checksum when encoding, and check this checksum when decoding.
 
 ## BufferReader & BufferWriter
-
 These classes are used internally to write information in buffers.

docs/hierarchical.md

@@ -1,15 +1,10 @@
----
-title: HDKeys
-description: Lets you create and derive extended public and private keys according to the BIP32 standard for Hierarchical Deterministic (HD) keys.
----
 # HDKeys
+Create and derive extended public and private keys according to the BIP32 standard for Hierarchical Deterministic (HD) keys.
 
 ## Hierarchically Derived Keys
-
 Bitcore provides full support for [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki), allowing for many key management schemas that benefit from this property. Please be sure to read and understand the basic concepts and the warnings on that BIP before using these classes.
 
 ## HDPrivateKey
-
 An instance of a [PrivateKey](privatekey.md) that also contains information required to derive child keys.
 
 Sample usage:
@@ -29,11 +24,9 @@ var address = derived.privateKey.toAddress();
 
 // obtain HDPublicKey
 var hdPublicKey = hdPrivateKey.hdPublicKey;
-
 ```
 
 ## HDPublicKey
-
 An instance of a PublicKey that can be derived to build extended public keys. Note that hardened paths are not available when deriving an HDPublicKey.
 
 ```javascript

docs/networks.md

@@ -1,24 +1,16 @@
----
-title: Networks
-description: A simple interface to handle livenet and testnet bitcoin networks.
----
 # Networks
-
-## Description
-
 Bitcore provides support for the main bitcoin network as well as for `testnet3`, the current test blockchain. We encourage the use of `Networks.livenet` and `Networks.testnet` as constants. Note that the library sometimes may check for equality against this object. Please avoid creating a deep copy of this object.
 
 The `Network` namespace has a function, `get(...)` that returns an instance of a `Network` or `undefined`. The only argument to this function is some kind of identifier of the network: either its name, a reference to a Network object, or a number used as a magic constant to identify the network (for example, the value `0` that gives bitcoin addresses the distinctive `'1'` at its beginning on livenet, is a `0x6F` for testnet).
 
 ## Setting the Default Network
-
 Most projects will only need to work with one of the networks. The value of `Networks.defaultNetwork` can be set to `Networks.testnet` if the project will need to only to work on testnet (the default is `Networks.livenet`).
 
 ## Network constants
-
 The functionality of testnet and livenet is mostly similar (except for some relaxed block validation rules on testnet). They differ in the constants being used for human representation of base58 encoded strings. These are sometimes referred to as "version" constants.
 
 Take a look at this modified snippet from [networks.js](https://github.com/bitpay/bitcore/blob/master/lib/networks.js)
+
 ```javascript
 var livenet = new Network();
 _.extend(livenet, {

docs/privatekey.md

@@ -1,22 +1,14 @@
----
-title: Private Key
-description: A simple interface to generate, import and handle private keys.
----
 # Private Key
-
-## Description
-
 Represents a bitcoin private key and is needed to be able to spend bitcoin and sign transactions. See the official [Bitcoin Wiki](https://en.bitcoin.it/wiki/Private_key) for more information about private keys. A PrivateKey in Bitcore is an immutable object that has methods to import and export into a variety of formats including [Wallet Import Format](https://en.bitcoin.it/wiki/Wallet_import_format).
 
 ## Instantiate a Private Key
-
 Here is how to create a new private key. It will generate a new random number using `window.crypto` or the Node.js `crypto` library.
 
 ```javascript
 var privateKey = new PrivateKey();
 
 // Creates a private key from a hexa encoded number
-var privateKey2 = new PrivateKey('b221d9dbb083a7f33428d7c2a3c3198ae925614d70210e28716ccaa7cd4ddb79'); 
+var privateKey2 = new PrivateKey('b221d9dbb083a7f33428d7c2a3c3198ae925614d70210e28716ccaa7cd4ddb79');
 ```
 
 To export and import a private key, you can do the following:
@@ -39,7 +31,6 @@ var address = publicKey.toAddress(Networks.livenet);
 ```
 
 ## Validating a Private Key
-
 The code to do these validations looks like this:
 
 ```javascript

docs/publickey.md

@@ -1,18 +1,9 @@
----
-title: Public Key
-description: A simple interface for handling private keys.
----
 # Public Key
-
-## Description
-
-Represents a bitcoin public key and is needed to be able to receive bitcoin, as is usually represented as a bitcoin [Address](address.md).
-See the official [Bitcoin Wiki](https://en.bitcoin.it/wiki/Technical_background_of_version_1_Bitcoin_addresses).
+Represents a bitcoin public key and is needed to be able to receive bitcoin, as is usually represented as a bitcoin [Address](address.md). See the official [Bitcoin Wiki](https://en.bitcoin.it/wiki/Technical_background_of_version_1_Bitcoin_addresses).
 
 A PublicKey in Bitcore is an immutable object and can be instantiated from a [Point](crypto.md), string, [PrivateKey](privatekey.md), Buffer or a [BN](crypto.md).
 
 ## Instantiate a Public Key
-
 Here is how to instantiate a public key:
 
 ```javascript
@@ -24,11 +15,9 @@ var publicKey = new PublicKey(privateKey);
 
 // from a der hex encoded string
 var publicKey2 = new PublicKey('02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0be551b5dc');
-
 ```
 
 ## Validating a Public Key
-
 A public key point should be on the [secp256k1](https://en.bitcoin.it/wiki/Secp256k1) curve, instantiating a new PublicKey will validate this and will throw an error if it's invalid. To check that a public key is valid:
 
 ```javascript
@@ -38,13 +27,10 @@ if (PublicKey.isValid('02a1633cafcc01ebfb6d78e39f687a1f0995c62fc95f51ead10a02ee0
 ```
 
 ## Compressed vs Uncompressed
-
-It's important to note that there are two possible ways to represent a public key.
-The standard is *compressed* and includes the X value and parity (as represented above in the documentation).
-There is also a longer version that is *uncompressed* which includes both X and Y values. Using this encoding will generate a different bitcoin address, so be careful when selecting the encoding.
-Uncompressed public keys start with 0x04; compressed public keys begin with 0x03 or 0x02 depending on whether they're greater or less than the midpoint of the curve. These prefix bytes are all used in official secp256k1 documentation.
+It's important to note that there are two possible ways to represent a public key. The standard is _compressed_ and includes the X value and parity (as represented above in the documentation). There is also a longer version that is _uncompressed_ which includes both X and Y values. Using this encoding will generate a different bitcoin address, so be careful when selecting the encoding. Uncompressed public keys start with 0x04; compressed public keys begin with 0x03 or 0x02 depending on whether they're greater or less than the midpoint of the curve. These prefix bytes are all used in official secp256k1 documentation.
 
 Example:
+
 ```javascript
 > var bitcore = require('bitcore');