git.stevedylan.dev

chore: add link to post 5ecb5b58

Steve · 2025-08-31 14:00 1 file(s) · +1 −1

src/content/post/turning-natspec-into-markdown-ui.mdx +1 −1


All we know about this function is it probably sets a new number, but why? What is the number for? We might be able to answer these questions by looking at the source code of the contract itself, but there are many cases where we have no idea what a paramter is used for. This is something that [Seb brought up](https://farcaster.xyz/seb/0xf5694e6e) on Farcaster this weekend, stating "There should be some sort of universal markup language for every smart contract (that isn't an ABI) that allows anyone to easily interact onchain." 

This got me wondering if the NatSpec could be used to help solve this problem. If you're not familiar with it, the [NatSpec](https://docs.soliditylang.org/en/latest/natspec-format.html) works a lot like JSDoc where the developer can leave comments in a particular format that can be used by the compiler to create documentation or even SDKs and CLIs. It's been in Solidity for years and has actually been used by OpenZeppelin's documentation to generate API references. While most of the tags handle things like parameters or returns, the `@notice` tag can be used as a general description and be filled with whatever we want to write, so why not markdown? It doesn't stop there though. What if we could build entire UIs out of the NatSpec? Thanks to a new library / proposed standard called Markdown UI I was able to build a [MVP](https://natspec-ui.orbiter.website) of this idea, and in this post I'll show you how it works!
This got me wondering if the NatSpec could be used to help solve this problem. If you're not familiar with it, the [NatSpec](https://docs.soliditylang.org/en/latest/natspec-format.html) works a lot like JSDoc where the developer can leave comments in a particular format that can be used by the compiler to create documentation or even SDKs and CLIs. It's been in Solidity for years and has actually been used by OpenZeppelin's documentation to generate API references. While most of the tags handle things like parameters or returns, the `@notice` tag can be used as a general description and be filled with whatever we want to write, so why not markdown? It doesn't stop there though. What if we could build entire UIs out of the NatSpec? Thanks to a new library / proposed standard called [Markdown UI](https://markdown-ui.com/) I was able to build a [MVP](https://natspec-ui.orbiter.website) of this idea, and in this post I'll show you how it works!

The first thing you need to do is write up the markdown as NatSpec in the smart contract.


34	34
35	35		All we know about this function is it probably sets a new number, but why? What is the number for? We might be able to answer these questions by looking at the source code of the contract itself, but there are many cases where we have no idea what a paramter is used for. This is something that [Seb brought up](https://farcaster.xyz/seb/0xf5694e6e) on Farcaster this weekend, stating "There should be some sort of universal markup language for every smart contract (that isn't an ABI) that allows anyone to easily interact onchain."
36	36
37		-	This got me wondering if the NatSpec could be used to help solve this problem. If you're not familiar with it, the [NatSpec](https://docs.soliditylang.org/en/latest/natspec-format.html) works a lot like JSDoc where the developer can leave comments in a particular format that can be used by the compiler to create documentation or even SDKs and CLIs. It's been in Solidity for years and has actually been used by OpenZeppelin's documentation to generate API references. While most of the tags handle things like parameters or returns, the `@notice` tag can be used as a general description and be filled with whatever we want to write, so why not markdown? It doesn't stop there though. What if we could build entire UIs out of the NatSpec? Thanks to a new library / proposed standard called Markdown UI I was able to build a [MVP](https://natspec-ui.orbiter.website) of this idea, and in this post I'll show you how it works!
	37	+	This got me wondering if the NatSpec could be used to help solve this problem. If you're not familiar with it, the [NatSpec](https://docs.soliditylang.org/en/latest/natspec-format.html) works a lot like JSDoc where the developer can leave comments in a particular format that can be used by the compiler to create documentation or even SDKs and CLIs. It's been in Solidity for years and has actually been used by OpenZeppelin's documentation to generate API references. While most of the tags handle things like parameters or returns, the `@notice` tag can be used as a general description and be filled with whatever we want to write, so why not markdown? It doesn't stop there though. What if we could build entire UIs out of the NatSpec? Thanks to a new library / proposed standard called [Markdown UI](https://markdown-ui.com/) I was able to build a [MVP](https://natspec-ui.orbiter.website) of this idea, and in this post I'll show you how it works!
38	38
39	39		The first thing you need to do is write up the markdown as NatSpec in the smart contract.
40	40