solidusio · tvdeyen · May 3, 2018 · Apr 25, 2018 · Apr 25, 2018 · Apr 25, 2018
diff --git a/guides/adjustments/overview.md b/guides/adjustments/overview.md
@@ -1,4 +1,4 @@
-# Overview of adjustments
+# Overview
 
 The `Spree::Adjustment` model is used to track price adjustments. For example,
 taxes and promotions generate price adjustments. Adjustments can be either a
@@ -75,9 +75,9 @@ can be adjustables:
 
 ## Charges vs. credits
 
-Adjustments can be positive or negative amounts. For convenience, you can use the
-[adjustment scopes](adjustment-scopes.html.markdown) `charge` or `credit` to
-retrieve only positive or negative amounts.
+Adjustments can be positive or negative amounts. For convenience, you can use
+the [adjustment scopes](#adjustment-scopes) `charge` or `credit` to retrieve
+only positive or negative amounts.
 
 ## Adjustment scopes
 

diff --git a/guides/assets/override-solidus-assets.md b/guides/assets/override-solidus-assets.md
@@ -7,18 +7,21 @@ assets and views.
 The custom assets you create for a Solidus extension or the frontend and backend
 of a store would not be automatically included and served to clients. For more
 information about adding your own custom assets to Solidus, see the
-[Asset management](asset-management.md#managing-application-assets) article.
+[Asset management][asset-management] article.
 
 This article provides an overview of how Solidus manages assets. Note that it
 assumes that you are using the `solidus_frontend` and `solidus_backend` gems
 that are included as part of a typical Solidus installation.
 
+[asset-management]: asset-management.md#managing-application-assets
+
 ## Overrides and upgrading Solidus
 
-We recommend overriding assets as little as possible. This makes maintaining
-your application simpler in the long term. The `solidus_frontend` and
-`solidus_backend` gems change with each version, and overrides for one version
-might not be effective for the next.
+We recommend overriding assets as little as possible. Overriding assets makes
+maintaining your application more complicated in the long term.
+
+The `solidus_frontend` and `solidus_backend` gems change with each version, and
+overrides for one version might not be effective for the next.
 
 ## Override individual CSS or JavaScript definitions
 
@@ -57,7 +60,7 @@ footer#footer {
 ### JavaScript
 
 Just like you can override a single CSS definition being provided by a gem, you
-can rewrite an existing JavaScipt function..
+can rewrite an existing JavaScript function.
 
 For example, if you wanted to override the `Spree.showVariantImages` method from
 `solidus_frontend`'s [`product.js`][product-js], you can do so from any

diff --git a/guides/calculators/overview.md b/guides/calculators/overview.md
@@ -124,5 +124,5 @@ of custom calculator you may want to build:
 - [Custom shipping calculators][custom-shipping-calculators]
 - [Custom tax calculators][custom-tax-calculators]
 
-[custom-shipping-calculators]: ../shipments/custom-shipping-calculators.html
-[custom-tax-calculators]: ../taxation/custom-tax-calculators.html
+[custom-shipping-calculators]: ../shipments/custom-shipping-calculators.md
+[custom-tax-calculators]: ../taxation/custom-tax-calculators.md
diff --git a/guides/calculators/promotion-calculators.md b/guides/calculators/promotion-calculators.md
@@ -158,8 +158,8 @@ Item". It has the following preference:
 - `percent`: The percentage discount that should be given to each applicable
   line item.
 
-[distributed-amount]: https://github.com/solidusio/solidus/blob/master/core/app/models/spree/calculator/distributed_amount.rb)
-[percent-on-line-item]: https://github.com/solidusio/solidus/blob/master/core/app/models/spree/calculator/percent_on_line_item.rb)
+[distributed-amount]: https://github.com/solidusio/solidus/blob/master/core/app/models/spree/calculator/distributed_amount.rb
+[percent-on-line-item]: https://github.com/solidusio/solidus/blob/master/core/app/models/spree/calculator/percent_on_line_item.rb
 
 ## Free shipping promotions
 

diff --git a/guides/extensions/installing-extensions.md b/guides/extensions/installing-extensions.md
@@ -31,7 +31,7 @@ of supported extensions can be found at [extensions.solidus.io][extensions].
 You can use the [`solidus_cmd`][solidus-cmd] gem if you want to start creating a
 new Solidus extension.
 
-[extensions]: http://extensions.solidusio.io
+[extensions]: http://extensions.solidus.io
 [solidus-cmd]: https://github.com/solidusio/solidus_cmd
 
 ## Soliton

diff --git a/guides/getting-started/develop-solidus.md b/guides/getting-started/develop-solidus.md
@@ -35,7 +35,7 @@ databases instead of the default SQLite 3 database. For example:
 
 ```bash
 DB=postgresql bundle exec rake sandbox
-``` 
+```
 
 After the sandbox has been generated, you can change into its directory and
 start the server:
@@ -73,8 +73,9 @@ Solidus project:
 bash build.sh
 ```
 
-This runs using PostgreSQL by default, but it can be overridden by setting the
-`DB` environment variable to `DB=sqlite` or `DB=mysql`. For example: 
+The `build.sh` script runs using PostgreSQL by default, but it can be overridden
+by setting the `DB` environment variable to `DB=sqlite` or `DB=mysql`. For
+example:
 
 ```bash
 DB=mysql bash build.sh
@@ -118,5 +119,5 @@ new Solidus extension.
 
 [chromedriver]: https://sites.google.com/a/chromium.org/chromedriver/home
 [circleci]: https://circleci.com/gh/solidusio/solidus
-[extensions]: https://extensions.solidus.io
+[extensions]: http://extensions.solidus.io
 [solidus-cmd]: https://github.com/solidusio/solidus_cmd
diff --git a/guides/getting-started/first-time-installation.md b/guides/getting-started/first-time-installation.md
@@ -33,7 +33,7 @@ Rails](http://rubyonrails.org). To get the most out of Solidus, we recommend
 that you familiarize yourself with Ruby on Rails, as well as [the Ruby
 programming language](https://www.ruby-lang.org/) beforehand.
 
-Because Solidus is an Rails engine, much of what the [Rails Guide on
+Because Solidus is a Rails engine, much of what the [Rails Guide on
 Engines](http://guides.rubyonrails.org/engines.html) explains applies directly
 to Solidus, too.
 

diff --git a/guides/getting-started/installation-options.md b/guides/getting-started/installation-options.md
@@ -56,7 +56,7 @@ bundle exec rake db:seed                           # seeds your database
 
 ## Development environment performance gains
 
-You may noticed that your Solidus store runs slowly in development mode. You can
+You may notice that your Solidus store runs slowly in development mode. You can
 change some configuration to get performance gains.
 
 ### Turn off asset debugging

diff --git a/guides/index.md b/guides/index.md
@@ -7,6 +7,12 @@
  - [Asset Management](assets/asset-management.md)
  - [Override Solidus Assets](assets/override-solidus-assets.md)
 
+## Calculators
+ - [Overview](calculators/overview.md)
+ - [Promotion Calculators](calculators/promotion-calculators.md)
+ - [Shipping Calculators](calculators/shipping-calculators.md)
+ - [Tax Calculator](calculators/tax-calculator.md)
+
 ## Extensions
  - [Decorators](extensions/decorators.md)
  - [Installing Extensions](extensions/installing-extensions.md)
@@ -26,6 +32,7 @@
 
 ## Locations
  - [Countries And States](locations/countries-and-states.md)
+ - [Overview](locations/overview.md)
  - [Zones](locations/zones.md)
 
 ## Orders
@@ -35,10 +42,11 @@
  - [Update Orders](orders/update-orders.md)
 
 ## Payments
- - [Custom Gateway](payments/custom_gateway.md)
  - [Overview](payments/overview.md)
- - [Payment Method](payments/payment_method.md)
- - [Payment Processing](payments/payment_processing.md)
+ - [Payment Methods](payments/payment-methods.md)
+ - [Payment Service Providers](payments/payment-service-providers.md)
+ - [Payment Sources](payments/payment-sources.md)
+ - [Payments](payments/payments.md)
 
 ## Preferences
  - [Add Model Preferences](preferences/add-model-preferences.md)
@@ -61,27 +69,38 @@
  - [Promotion Rules](promotions/promotion-rules.md)
 
 ## Returns
+ - [Customer Returns](returns/customer-returns.md)
+ - [Overview](returns/overview.md)
+ - [Reimbursement Types](returns/reimbursement-types.md)
+ - [Reimbursements](returns/reimbursements.md)
  - [Return Authorizations](returns/return-authorizations.md)
+ - [Return Items](returns/return-items.md)
 
 ## Shipments
  - [Cartons](shipments/cartons.md)
  - [Custom Shipping Calculators](shipments/custom-shipping-calculators.md)
- - [Overview Of Shipments](shipments/overview-of-shipments.md)
+ - [Overview](shipments/overview.md)
  - [Shipment Setup Examples](shipments/shipment-setup-examples.md)
  - [Shipping Method Filters](shipments/shipping-method-filters.md)
  - [Solidus Active Shipping Extension](shipments/solidus-active-shipping-extension.md)
  - [Split Shipments](shipments/split-shipments.md)
  - [User Interface For Shipments](shipments/user-interface-for-shipments.md)
 
 ## Taxation
- - [Custom Tax Calculator](taxation/custom-tax-calculator.md)
+ - [Custom Tax Calculators](taxation/custom-tax-calculators.md)
  - [Displaying Prices](taxation/displaying-prices.md)
  - [Example Tax Setups](taxation/example-tax-setups.md)
- - [Overview Of Taxation](taxation/overview-of-taxation.md)
+ - [Overview](taxation/overview.md)
  - [Value Added Tax](taxation/value-added-tax.md)
 
+## Upgrades
+ - [Migrate From Spree](upgrades/migrate-from-spree.md)
+ - [Overview](upgrades/overview.md)
+ - [Versioning Guidelines](upgrades/versioning-guidelines.md)
+
 ## Users
  - [Addresses](users/addresses.md)
+ - [Custom Authentication](users/custom-authentication.md)
 
 ## Views
  - [Custom Frontend](views/custom-frontend.md)

diff --git a/guides/locations/index.md → guides/locations/overview.md b/guides/locations/index.md → guides/locations/overview.md
@@ -1,4 +1,4 @@
-# Locations
+# Overview
 
 In order to sell products, your store requires that you have locations set up.
 In Solidus, locations are split up into states, countries, and zones.

diff --git a/guides/locations/zones.md b/guides/locations/zones.md
@@ -107,9 +107,9 @@ with the required tax rates and any shipping methods you wish to use:
 | Contiguous States     | Purchases shipped to all other states       | 0        | FedEx Express, UPS Ground                   |
 | Canada                | Purchases shipped internationally to Canada | 0        | FedEx Express                               |
 
-All of the zones in this table would be state-based with the exception of the
-"Canada" zone, which you could configure as a country-based zone with a single
-country in it.
+All of the zones in this table would be state-based except for the "Canada"
+zone, which you could configure as a country-based zone with a single country in
+it.
 
 While you might choose to use zones differently in your own store, this example
 shows how you might want to group different states according to your own

diff --git a/guides/orders/display-total-methods.md b/guides/orders/display-total-methods.md
@@ -37,5 +37,5 @@ its [`format`][ruby-money-format] method:
 ```
 
 [ruby-money]: https://github.com/RubyMoney/money
-[ruby-money-format]: http://www.rubydoc.info/gems/money/Money/Formatting
+[ruby-money-format]: https://www.rubydoc.info/gems/money/Money:format
 
diff --git a/guides/orders/order-state-machine.md b/guides/orders/order-state-machine.md
@@ -16,7 +16,7 @@ There are six order states by default:
 If you go through the checkout provided in the `solidus_frontend` gem, you can
 see that there is a clearly defined step for each of these states during checkout.
 
-The `payment` state is optional and it's only triggered if `payment_required?` 
+The `payment` state is optional and it's only triggered if `payment_required?`
 returns `true`.
 
 The `complete` state is triggered in one of two ways:
@@ -47,7 +47,7 @@ def transition_forward
     @order.next
   end
 end
-``` 
+```
 
 If `next` returns `false`, then the order does not meet the criteria and does
 not transition to the next state.
@@ -57,13 +57,13 @@ not transition to the next state.
 ## Payments and shipments have their own state machines
 
 Note that a `Spree::Order` with the state `complete` does not mean that the
-payment has been processed or the order shipments have been shipped. See also the
-values of the `payment_state` and `shipment_state` attributes.
+payment has been processed or the order shipments have been shipped. See also
+the values of the [`payment_state`][payment-states] and
+[`shipment_state`][shipment-states] attributes.
 
 <!-- TODO:
-  Once it's merged, link to documentation about checkout. This section only
-  attempts to summarize some of what happens during the checkout flow.
-
-  It may be useful to link to the payments documentation once it's merged, too.
+  Documentation about the checkout flow could be extended.
 -->
 
+[payment-states]: ../payments/overview.md#payment-states
+[shipment-states]: ../shipments/overview.md#shipment-states
diff --git a/guides/orders/overview.md b/guides/orders/overview.md
@@ -71,7 +71,7 @@ information, see the [Display totals methods][display-total-methods] article.
 
 [display-total-methods]: display-total-methods.md
 [order-state-machine]: order-state-machine.md
-[shipment-states]: ../shipments/overview-of-shipments.md#shipping-states
+[shipment-states]: ../shipments/overview.md#shipping-states
 [special-instructions]: ../shipments/user-interface-for-shipments.md#shipping-instructions
 [update-orders]: update-orders.md
 
@@ -109,7 +109,7 @@ promotions) or increase it (via [shipments][shipments] and [taxes][taxes]).
   Add link to adjustments guide once it is merged.
 -->
 
-[taxes]: ../taxation/overview-of-taxation.md
+[taxes]: ../taxation/overview.md
 
 ### Shipments
 
@@ -124,7 +124,7 @@ item belongs to. Inventory units provide a link between the order and
 
 For more information, see the [Shipments][shipments] documentation.
 
-[shipments]: ../shipments/overview-of-shipments.md
+[shipments]: ../shipments/overview.md
 
 ### Addresses
 

diff --git a/guides/payments/custom_gateway.md b/guides/payments/custom_gateway.md
diff --git a/guides/payments/overview.md b/guides/payments/overview.md
@@ -7,7 +7,7 @@ The logic for processing payments is decoupled from Solidus's orders system.
 This allows you to easily define your own payment methods with custom
 processing logic.
 
-The payments system has many moving parts. The following lists summarizes the
+The payments system has many moving parts. The following lists summarize the
 essential parts of the payments system:
 
 1. **Payment service providers**. Before your store can have a functional
@@ -135,4 +135,4 @@ service provider.
 For more information about processing payments, see the [Payment
 processing][payment-processing] article.
 
-[payment-processing]: payment_processing.md
+[payment-processing]: payment-processing.md
diff --git a/guides/payments/payment-methods.md b/guides/payments/payment-methods.md
@@ -58,7 +58,7 @@ payment service provider for [processing][payment-processing]. If the
 administrator must manually capture payments. However, you can set any payment
 method to auto-capture payments.
 
-[payment-processing]: payment_processing.md
+[payment-processing]: payment-processing.md
 
 ### Application-wide auto-capture default
 
@@ -67,7 +67,7 @@ defaults to the value of your store's `Spree::Config[:auto_capture]` preference.
 
 ## Set a payment source class
 
-The `Spree::PaymentMethod` base class has a has a method called
+The `Spree::PaymentMethod` base class has a method called
 `payment_source_class`. It sets the payment source that should be associated
 with your payment method. When you are creating your own payment method, you
 need to define a `payment_source_class` (even if it is `nil`).

diff --git a/guides/payments/payment-processing.md b/guides/payments/payment-processing.md
@@ -14,7 +14,7 @@ includes the [`Spree::Payment::Processing` class][spree-payment-processing].
   merged.
 -->
 
-[payment-methods]: payment_method.md
+[payment-methods]: payment-methods.md
 [payment-service-providers]: payment-service-providers.md
 [psp]: https://en.wikipedia.org/wiki/Payment_service_provider
 [spree-payment-processing]: https://github.com/solidusio/solidus/blob/master/core/app/models/spree/payment/processing.rb

diff --git a/guides/payments/payment-sources.md b/guides/payments/payment-sources.md
@@ -12,7 +12,7 @@ Solidus includes some payment sources such as `Spree::CreditCard` and
 `Spree::StoreCredit`. However, your [payment method][payment-methods] could
 define any custom payment source in its `payment_source_class` method.
 
-[payment-methods]: payment-methods.html
+[payment-methods]: payment-methods.md
 
 ## Credit cards
 
@@ -31,4 +31,4 @@ storing customer data. See the [PCI Security Standards][pci] website for more
 information.
 
 [pci]: https://www.pcisecuritystandards.org
-[payment-processing]: payment_processing.md
+[payment-processing]: payment-processing.md
diff --git a/guides/preferences/class-extension-points.md b/guides/preferences/class-extension-points.md
@@ -75,7 +75,7 @@ end
 Now, when search is built it uses your extended `MyStore::ProductSearch`
 functionality instead of the default functionality.
 
-[search-base]: https://github.com/solidusio/solidus/blob/master/core/lib/spree/base.rb
+[search-base]: https://github.com/solidusio/solidus/blob/v2.4/core/lib/spree/core/search/base.rb
 
 ## Generating extension points
 

diff --git a/guides/products-and-variants/overview.md b/guides/products-and-variants/overview.md
@@ -1,4 +1,4 @@
-# Overview of products and variants
+# Overview
 
 Products and variants are integral to Solidus. While the `Spree::Product` and
 `Spree::Variant` models depend on each other, it is important to understand how

diff --git a/guides/products-and-variants/products.md b/guides/products-and-variants/products.md
@@ -21,8 +21,8 @@ Products have the following attributes:
    also targeted at search engines.
 - `meta_title`: Title to put in HTML `<title>` tag. If left blank, the product
    name is used instead.
-- `promotionable`: Determines whether or not promotions can apply to the
-   product. (Labeled "Promotable" in the admin interface.)
+- `promotionable`: Determines whether promotions can apply to the product.
+  (Labeled "Promotable" in the admin interface.)
 
 ## Variants