Feat: update V2 and V3 vault docs

README.md

@@ -53,7 +53,7 @@ In the `docs` folder:
 
 #### Versioned Documentation
 
-Versioning has changed. Because Yearn supports multiple products with their own versions, versioning is now done manually using folder structure to keep things organized. There are folders for all versions of the smart contract natspec documentation in:
+Versioning has changed. Because Yearn supports multiple products with their own versions, versioning is now done manually using folder structure to keep things organized. There are folders for all versions of the smart contract [NatSpec](https://docs.soliditylang.org/en/latest/natspec-format.html) documentation in:
 
 ```
 
@@ -120,3 +120,47 @@ npm run docusaurus docs:version 0.4.5
 ```
 
 If you are developing in Solidity and Foundry you can use `[forge-doc](https://book.getfoundry.sh/reference/forge/forge-doc)`
+
+### Custom Elements
+
+#### Detail Element
+
+This is a Detail element that contains other text inside. If you format the summary section as shown it renders markdown correctly.
+
+```
+<details className="customDetails">
+
+  <summary>
+
+  ## Title Here
+
+  </summary>
+
+### Subtitles as needed
+
+content here
+
+</details>
+```
+
+There is also a "customFaqDetails" css class that removes the borders.
+
+#### PrettyLink
+
+The PrettyLink element makes your links into button-like elements with subtle animation and yearn styling. These links will fill the full width of the markdown document. Can be used with naked links or with markdown style links.
+
+```
+<PrettyLink>[your link name](your-link-url)</PrettyLink>
+```
+
+#### Yearn Admonition
+
+There is a custom informational Yearn-styled admonition that can be used like any other admonition.
+
+```
+:::yearn-info[title-goes-here]
+
+text content
+
+:::
+```

docs/developers/data-services/yearn-data.md

@@ -36,8 +36,13 @@ Yearn Lens is a collection of smart contracts that collect data about V2 Yearn v
 
 ---
 
-<details className="customDetails">
-  <summary><h2>Deprecated Data Services</h2></summary>
+<details className="customFaqDetails">
+
+  <summary>
+
+## Deprecated Data Services
+
+  </summary>
 
 ### Yearn Exporter - No longer supported
 

docs/developers/v1/introduction.md

@@ -4,6 +4,12 @@ description: This documentation only covers v1 vaults.
 
 # v1 Vaults Overview
 
+:::warning
+
+This document describes the original implementation of Yearn's Vault and Governance systems. It gives a good sense of the bones of Yearn and is a place to build your intuition about how things work. These contracts are all mostly deprecated or superseded at this point, so if you are looking for information on actual implementations or to better understand the particulars of the current vaults, please review those specific docs.
+
+:::
+
 This document gives a _generalized and high level overview_ of how the protocol and its actors, smart contracts, and other services interact with each other. The aim is to build intuition about how Yearn products work.
 
 :::info

docs/developers/v3/overview.md

@@ -1,4 +1,4 @@
-# Overview
+# yVaults v3
 
 Yearn's V3 system is a decentralized suite of yield-generating products built to fit any need. It is designed to be un-opinionated and customizable infrastructure for the world to build on, making yield generation as safe, efficient, and easy as possible for all parties. Anyone can deploy a strategy or manage a vault. So whether you are a gas golfing expert, a degen looking to codify your personal yield farming strategy, or just an average crypto user looking to earn passive yield on your magical internet tokens, V3 is for you.
 
@@ -16,6 +16,25 @@ The most significant update to Yearn V3 from V2 was the introduction of "Tokeniz
 
 - [Vault Factory](https://github.com/yearn/yearn-vaults-v3/blob/master/contracts/VaultFactory.vy): A factory contract deployed by Yearn Governance that anyone can use to easily and trustlessly deploy new Allocator Vaults. Each Allocator Vault release will have its own factory.
 
+![image](/img/diagrams/yvaults-v3-more-detail.png)
+
+## Periphery Contracts
+
+V3 incorporates periphery contracts, which are extensible code blocks that can be attached to a yVault or work alongside it to extend functionality over and beyond core base logic. They are not required but can facilitate building around yVaults.
+
+A few examples of periphery contracts used in V3 are:
+
+- **4626 Router**: Wrapper that handles deposits and withdrawals to/from all vaults and strategies.
+- **Registry**: Handles adding and tracking strategies and vaults.
+- **Debt Allocator**: Can efficiently allocate debt to different strategies. Added to an Allocator Vault for the best yield opportunities.
+- **Accountant**: Handles changing fees for vault operations.
+- **Deposit/Withdraw Limit Modules**: Allows dynamic control over a vaults deposit or withdraw limits for full customization.
+- **Swappers**: Pre-built contracts for strategies to inherit to easily implement their desired swap logic.
+- **APR Oracles**: Retrieve the expected current APY on-chain for different vaults or strategies to properly allocate debt.
+- And any others you can come up with!
+
+To read more about the periphery contracts or where to find the current versions click [here](./periphery.md)
+
 ## Get started
 
 - [Integrating V3](/developers/v3/integrating_v3)

docs/getting-started/products/ylockers/ycrv/overview.md

@@ -1,6 +1,8 @@
 
 # yCRV Overview
 
+![image](/img/product-pages/ycrv-banner.png)
+
 ## What is yCRV?
 
 yCRV is Yearn's veCRV yLocker product. It is designed to tokenize the different benefits of a [veCRV position](https://resources.curve.fi/crv-token/vecrv/) in a simple, user-friendly way. Let's review the basics of liquid locker tokens like yCRV:

docs/getting-started/products/ylockers/yprisma/overview.md

@@ -1,5 +1,7 @@
 # yPRISMA Overview
 
+![image](/img/product-pages/yprisma-banner.png)
+
 Claim and deposit at [yprisma.yearn.fi](https://yprisma.yearn.fi)
 
 ## What is yPRISMA?

docs/getting-started/products/yvaults/overview.md

@@ -1,37 +1,41 @@
-# Overview
+# yVaults
 
-## What are yVaults?
+:::yearn-info[WHAT IS A yVAULT ANYWAY?]
 
-[yVaults](https://yearn.fi/vaults) are like savings accounts for your crypto assets. They accept your deposit, then route it through strategies which seek out the highest yield available in DeFi.
+Yearn Vaults are like crypto savings accounts in cyberspace. You deposit your assets, and Yearn's smart contracts put them to work within the DeFi ecosystem, returning the earned yield back to you.
 
-![image](https://github.com/yearn/yearn-devdocs/assets/7863230/af161f3d-ed71-4010-84ba-e1bfab66d782)
+However, unlike a bank account - none of this takes place behind closed doors (no offense to doors). Decentralised Finance uses public blockchains, meaning you are in control of your assets and can see where they are at all times. Nothing is hidden and everything is auditable by anyone, at any time.
 
-## yVault Fee Structure
+With the advent of v3, Vaults can now be made out of a single strategy for your assets, or a collection of multiple strategies which balance your funds between them. Users now have more control over where they want their funds to go and a wider range of risk appetites.
 
-**Performance Fee**: Deducted from yield earned every time a vault harvests a strategy.
+Go you!
 
-**Management Fee**: Flat rate taken from vault deposits over a year. The fee is extracted by minting new shares of the vault, thereby diluting vault participants. This is done at the time of harvest, and calculated based on time since the previous harvest.
+:::
 
-The old structure used before the changes brought by [YIP-69](https://gov.yearn.fi/t/yip-69-reduce-and-cap-fees-through-yrates/12588) was 20% performance fees and 2% management fees, but this has changed and vaults now have a dynamic fee structure. Single asset vaults have no management fee. Fee values for all yVaults can be checked in real-time at [yearn.watch](https://yearn.watch/)
+<PrettyLink>[Still Confused? Click here for an ELI-5 explainer](yvaults-faq#yvaults-eli-5)</PrettyLink>
 
-*Example YFI yVault fee structure at the time of writing:*  
+## yVault Types
 
-| Fee Type        | Value   |
-|-----------------|-----|
-| Management Fee  | 0%  |
-| Performance Fee | 20% |
+Over the years, Yearn has developed 3 versions of the yVault products: v1, v2, and v3. Super creative, we know!
 
-On the [yearn.fi](https://yearn.fi/) user interface, yield is displayed as net APY. This means that both fees and compounding returns are taken into consideration in the rates presented. Since harvests don't occur on a set basis, yield is usually estimated based on historical data. For more information, see [How to Understand yVault ROI](https://docs.yearn.fi/getting-started/guides/how-to-understand-yvault-roi)
+- [**v1 yVaults**](../../../developers/v1/introduction) are the OG vaults and are mostly phased out (*deprecated* in developer-speak).
 
-- For vaults deployed by the vault [factory](https://docs.yearn.fi/getting-started/products/yvaults/vault-factory) the performance fee is 10% instead of 20%.
+- [**v2 yVaults**](./v2) are the reliable, workhorse vaults that you know and love. They started out focused on the Curve ecosystem and are still used when creating vaults for Curve pools.
+
+- [**v3 yVaults**](./v3) are the new cool vaults on the block. They are designed to interoperate using the ERC-4626 standard and have a number of new features to make them safer and easier to use and create.
+
+## yVault Fee Structure
+
+yVaults have 2 potential fees that can be charged on deposited funds:
+
+**Performance Fee**: Deducted from yield earned every time a vault harvests a strategy.
+
+**Management Fee**: Flat rate taken from vault deposits over a year. The fee is extracted by minting new shares of the vault, thereby diluting vault participants. This is done at the time of harvest, and calculated based on time since the previous harvest.
 
-## v2 yVault Improvements
+Prior to [YIP-69](https://gov.yearn.fi/t/yip-69-reduce-and-cap-fees-through-yrates/12588), vaults had 20% performance fees and 2% management fees, but this has changed and yVaults now have a dynamic fee structure.
 
-- **Up to 20 strategies per vault:** This will increase the flexibility to manage capital efficiently during different market scenarios. Each strategy has a capital cap. This is useful to avoid over-allocating funds to a strategy that cannot increase APY anymore.
-- **Strategist and Guardian are the new Controllers:** The Controller concept is not available in V2 yVaults and has been replaced by a Guardian and the Strategy creator \(strategist\). These 2 actors oversee strategy performance and are empowered to take action to improve capital management or act on critical situations.
-- **Automated vault housekeeping \(Keep3r network\):** `harvest()` and `earn()` calls are now automated through the Keep3r bots network. These 2 function calls are used to purchase new underlying collateral by selling the earned tokens while moving the profits back to the vault and later into strategies. The keep3r network takes the heavy lifting of doing these calls and running with the gas costs in exchange for keep3r tokens. This approach unloads humans from these housekeeping tasks.
-- **No Withdrawal Fee**: The one-time fee charged on balance upon withdrawal has been turned off for all vaults and only existed in the v1 iteration.
+Single asset vaults generally have no management fee. Fee values for all yVaults can be checked in real-time at [yearn.fi](https://yearn.fi/)
 
-## v3 yVaults
+- On the [yearn.fi](https://yearn.fi/) user interface, yield is displayed as net APY. This means that both fees and compounding returns are taken into consideration in the rates presented. Since harvests don't occur on a set basis, yield is usually estimated based on historical data. For more information, see [How to Understand yVault ROI](../../guides/how-apy-works)
 
-The newest version of yVaults are EIP-4626 compatible and allow for tokenized strategies, read more: https://docs.yearn.fi/getting-started/products/yvaults/v3
+- For vaults deployed by the vault [factory](/developers/v2/vault-factory) the performance fee is 10% instead of 20%.

docs/getting-started/products/yvaults/v2.md

@@ -0,0 +1,22 @@
+# yVaults v2
+
+## Overview
+
+The second iteration of yVaults are auto-compounding contracts that allow depositors to earn and compound yield on deposited assets. These are still the trusty workhorse vaults for Curve, Velodrome, and Aerodrome LP positions. They allow multiple strategies and can be automatically harvested, but they have mostly been superseded by the [V3](./v3) architecture for single asset vaults and other more exotic asset types. They are not ERC-4626 compatible, nor as flexible as the newer V3 vaults.
+
+![image](/img/diagrams/yvaults-v2.png)
+
+## v2 yVault Improvements
+
+- **Up to 20 strategies per vault:** This will increase the flexibility to manage capital efficiently during different market scenarios. Each strategy has a capital cap. This is useful to avoid over-allocating funds to a strategy that cannot increase APY anymore.
+- **Strategist and Guardian are the new Controllers:** The Controller concept is not available in V2 yVaults and has been replaced by a Guardian and the Strategy creator \(strategist\). These 2 actors oversee strategy performance and are empowered to take action to improve capital management or act on critical situations.
+- **Automated vault housekeeping \(Keep3r network\):** `harvest()` and `earn()` calls are now automated through the Keep3r bots network. These 2 function calls are used to purchase new underlying collateral by selling the earned tokens while moving the profits back to the vault and later into strategies. The keep3r network takes the heavy lifting of doing these calls and running with the gas costs in exchange for keep3r tokens. This approach unloads humans from these housekeeping tasks.
+- **No Withdrawal Fee**: The one-time fee charged on balance upon withdrawal has been turned off for all vaults and only existed in the v1 iteration.
+
+## Read More
+
+**V2 developer docs:** <PrettyLink>[https://docs.yearn.fi/developers/v2/getting-started](/developers/v2/getting-started)</PrettyLink>
+
+**dApp:** <PrettyLink>https://yearn.fi/vaults</PrettyLink>
+
+**Guides** <PrettyLink>[V2 Interface Guide](/getting-started/guides/using-yearn-v2)</PrettyLink>

docs/getting-started/products/yvaults/v3.md

@@ -1,8 +1,20 @@
-# Overview
+# yVaults V3
+
+![image](/img/product-pages/v3-banner.png)
+
+## Overview
+
+**V3 Vaults are the newest, shiniest yVaults. More flexibility, better security, more Yearn goodness!**
+
+Yearn's v3 yVaults are a decentralized suite of yield-generating products built to fit any need. They are designed to be un-opinionated and customizable infrastructure for the world to build on, making yield generation as safe, efficient, and easy as possible for all parties.
 
 Version 3 of yVaults iterates on Version 2 by increasing its robustness and developing Yearn’s path towards further decentralization, while keeping the same proven product (yield-bearing tokens). Version 3 has all the same functionality as Version 2, but with many more added benefits and improvements to continue to grow the Yearn ecosystem.
 
-V3 also sees the introduction of "Tokenized Strategies". Strategies are now capable of being standalone 4626 vaults themselves. These single-strategy vaults can be used as stand-alone vaults or easily added as a strategy to any of the multi-strategy "Allocator Vaults".
+V3 also sees the introduction of "Tokenized Strategies". Strategies are now capable of being standalone 4626 vaults themselves. These single-strategy vaults can be used as stand-alone vaults or easily added as a strategy to a Multi-Strategy Vault.
+
+![image](/img/diagrams/yvaults-v3-more-detail.png)
+
+## v3 yVault Improvements
 
 Version 3 of yVaults improves on Version 2 by:
 
@@ -13,33 +25,10 @@ Version 3 of yVaults improves on Version 2 by:
 - Decreasing gas costs to report profits and update debts.
 - Adding new product and vault types.
 
-[VaultV3 Specification](https://github.com/yearn/yearn-vaults-v3/blob/master/TECH_SPEC.md)
-
-[Tokenized Strategy Specification](https://github.com/yearn/tokenized-strategy/blob/master/SPECIFICATION.md)
-
-## Periphery Contracts
-
-V3 incorporates periphery contracts, which are extensible code blocks that can be attached to a yVault or work alongside it to extend functionality over and beyond core base logic. They are not required but can facilitate building around yVaults.
-
-A few examples of periphery contracts used in V3 are:
-
-- **4626 Router**: Wrapper that handles deposits and withdrawals to/from all vaults and strategies.
-- **Registry**: Handles adding and tracking strategies and vaults.
-- **Debt Allocator**: Can efficiently allocate debt to different strategies. Added to a Allocator Vault for the best yield opportunities.
-- **Accountant**: Handles changing fees for vault operations.
-- **Deposit/Withdraw Limit Modules**: Allows dynamic control over a vaults deposit or withdraw limits for full customization.
-- **Swappers**: Pre-built contracts for strategies to inherit to easily implement their desired swap logic.
-- **APR Oracles**: Retrieve the expected current APY on-chain for different vaults or strategies to properly allocate debt.
-- And any others you can come up with!
-
-To read more about the periphery contracts or where to find the curren versions click [here](../../../developers/v3/periphery)
-
 ## Read More
 
-**For more information visit the V3 developer section: https://docs.yearn.fi/developers/v3/overview**
+**V3 developer docs:** <PrettyLink>[https://docs.yearn.fi/developers/v3/overview](/developers/v3/overview)</PrettyLink>
+
+**dApp:** <PrettyLink>https://yearn.fi/v3</PrettyLink>
 
-- https://github.com/yearn/yearn-vaults-v3
-- https://github.com/yearn/tokenized-strategy
-- https://medium.com/iearn/yearnv3-motivation-and-design-107840cb4844
-- https://erc4626.info/
-- https://eips.ethereum.org/EIPS/eip-4626
+**Guides** <PrettyLink>[V3 Interface Guide](/getting-started/guides/using-yearn-v3)</PrettyLink>