Follow-up user documentation

[alcuadrado]

This issue includes a TODO list of things that should be added to the user facing documentation, but have lower priority than #142.

TODO

These are lists of files that are already present in the repo, including their frontmatter. All you need to do is change the extension from .todo to .mdx and write their content.

• Guides

  • src/content/docs/docs/guides/forking.todo — Add forking guide #179
  • src/content/docs/docs/guides/command-line-completion.todo — Not implemented yet
  • src/content/docs/docs/guides/hardhat-console.todo — Add console guide #181
  • src/content/docs/docs/guides/hardhat-node.todo — Add hardhat node guide #182
  • src/content/docs/docs/guides/testing/using-mocha.todo — TBD: See below
  • src/content/docs/docs/guides/testing/using-node-test.todo — TBD: See below

• Cookbook

  • src/content/docs/docs/cookbook/block-timestamp-manipulation.todo
  • src/content/docs/docs/cookbook/flattening-contracts.todo
  • src/content/docs/docs/cookbook/mocha-and-nodejs-tests-together.todo
  • src/content/docs/docs/cookbook/mocha-test-vscode.todo
  • src/content/docs/docs/cookbook/multiple-transactions-per-block.todo
  • src/content/docs/docs/cookbook/nodejs-test-vscode.todo

• Reference

  • src/content/docs/docs/reference/json-rpc-extensions.todo
  • src/content/docs/docs/reference/solidity-cheatcodes.todo

• Explanations

  • src/content/docs/docs/explanations/network-forking.todo
  • src/content/docs/docs/explanations/solidity-build-system.todo
  • src/content/docs/docs/explanations/typescript-support.todo

Higher-level tasks

TypeScript test runners and libraries relationship

Currently, the guides explaining how to test in typescript are two: one using mocha+ethers, and another one using node:test+viem. They are intentional symmetrical, and have almost the same content.

While this works well for these recommended setups, it seems to imply that if you use ethers you must use mocha, and the same with node:test and viem. We should think about how to do this.

It's also not super clear that most of what applies to testing with viem/ethers also applies to scripts and tasks. That may be just a simple comment that's missing.

Forking another network

It's unclear if having a src/content/docs/docs/guides/forking.todo guide will be enough. This is because forking affects both TypeScript and Solidity tests, and they provide different apis/configs to work with them.

We may be able to do it with a single guide, and link it from every other testing guide.

Multichain support

We should reiterate more than Hardhat 3 has multichain support. We should comment that on every testing guide.

(Done in #185)

Hardhat ledger

We need to have a guide about it. Its readme is in good state, but not easy to find. This should comment that it works with Ignition.

Migration guides

From Hardhat 2

It's not in a very minimal state. We should improve it, and also think about how to guide the users to consider modernizing their stack. (Some improvements: #188)

From Hybrid projects

(@fvictorio)

From Foundry

Hasn't been started

hardhat-viem's README.md needs improvements

The readme don't explain clearly when it's used, and it doesn't have a reference section.

(Done in NomicFoundation/hardhat#7705)

Potentially revisit the simulated networks explanation

I used more help than usual from claude, as i was running out of time. It looks more like a showcase than an explanation. Maybe we should revisit it.

At the same time, there's not so much to EXPLAIN, apart form the custom features.

(Done in #186)

LLM starlight improvements

We seriously should consider configuring starlight to play nicer with LLMs.

There are at least these plugins:

• https://github.com/corsfix/starlight-contextual-menu: Which fails out of the box, maybe because we have custom pages.
• https://github.com/delucis/starlight-llms-txt: This requires further consideration, as it may kill the LLM's context.

Uninstall unsupported packages during HH2 -> HH3 migration

Document a recommendation to uninstall packages and plugins that do not support Hardhat 3. Provide a list of commonly used incompatible packages and plugins.

• @typechain/hardhat