Restructure docs to make the right information more easily findable #51

marcocastignoli · 2026-01-20T15:30:30Z

This PR completely revamps Sourcify documentation, restructuring the menu and adding new pages

netlify · 2026-01-20T15:30:36Z

✅ Deploy Preview for sourcify-docs ready!

Name	Link
🔨 Latest commit	`ca44901`
🔍 Latest deploy log	https://app.netlify.com/projects/sourcify-docs/deploys/696f9f9aadab580008db9843
😎 Deploy Preview	https://deploy-preview-51--sourcify-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

manuelwedler · 2026-01-26T09:45:08Z

I'm currently reviewing it and it looks great so far!

Just one note that didn't fit to any file: Can we change the styling of the menu a bit?

I tried it myself and got this:

By adding this to custom.css:

.theme-doc-sidebar-item-category-level-1 > .menu__list-item-collapsible,
.theme-doc-sidebar-item-link-level-1.menu__list-item:not(:first-child),
.theme-doc-sidebar-item-link-level-1 {
  margin-top: 1rem;
}

.theme-doc-sidebar-item-category-level-1 > .menu__list-item-collapsible > .menu__link,
.theme-doc-sidebar-item-link-level-1 > .menu__link {
  font-weight: 700;
}

manuelwedler

Great restructuring! I like it a lot :)

manuelwedler · 2026-01-26T09:15:29Z

docs/0. Intro.md

+
+Sourcify ([sourcify.dev](https://sourcify.dev)) is a source-code verification service for Ethereum smart contracts supporting Solidity and Vyper. Sourcify is fully commited to Open-source, Open-data and Open-standards in smart-contract verification instead of siloed, propriety services. We foster these values across the ecosystem and work actively to push the status-quo in this direction.
+
+Different than other verification services, Sourcify leverages the [Solidity metadata](/docs/metadata/) and its integrity hash to find [exact matches](/docs/exact-match-vs-match/) of Solidity contracts (see [the playground](https://playground.sourcify.dev)).


Below this paragraph, we could add a short explanation how the docs are structured and where to go next.

Yes I think this page should give a nice overview of Sourcify, source code verification and the docs specifically.

We can skip it for now and I can look at this later

manuelwedler · 2026-01-26T09:55:01Z

docs/1. intro.mdx

-title: Sourcify Docs
---
-
-import EmbedReadmeIntro from "./EmbedReadmeIntro";


we can also delete EmbedReadmeIntro.jsx

manuelwedler · 2026-01-26T10:13:06Z

docs/4. Integrate Sourcify/2. Typescript libraries/1. lib-sourcify.mdx

+---
+
+:::info
+lib-sourcify is used to directly verify contracts, it's NOT a wrapper around the Sourcify API. lib-sourcify works also in the browser, allowing source code verification to be executed in the user environment.


Suggested change

lib-sourcify is used to directly verify contracts, it's NOT a wrapper around the Sourcify API. lib-sourcify works also in the browser, allowing source code verification to be executed in the user environment.

lib-sourcify is used to directly verify contracts, it's NOT a wrapper around the Sourcify API. It supports Node.js and browser environments.

Applications can integrate lib-sourcify in their frontends. This allows for verifying contract sources on the user's end and minimizes trust towards Sourcify. You can find an example [here](/blog/recap-2025/#lib-sourcify-on-browser-local-verification).

manuelwedler · 2026-01-26T10:29:25Z

docs/6. Run your own Sourcify instance/6 Tests.md

I would drop this page actually

manuelwedler · 2026-01-26T10:37:44Z

docs/20. databaseMigration.md

-slug: /database-migration
---
-
-# Migration from Filesystem to Database


I wouldn't drop this page, because not all custom instances have upgraded yet. Can we add it to the "Run your own Sourcify instance" section?

manuelwedler · 2026-01-26T12:15:17Z

docs/3. Explore the Verified contracts data/2. Signatures database.md

-# Signature Database
+---
+id: signature-database
+slug: /signature-database


Suggested change

slug: /signature-database

slug: /repository/signature-database

This is how the page was reached before

manuelwedler · 2026-01-26T12:17:40Z

docs/3. Verification/9. vyper.md

---
-id: vyper
-title: Vyper verification
-slug: /vyper


we could add a redirect from /docs/vyper to supported languages (inside docusaurus.config.js)

manuelwedler · 2026-01-26T12:17:57Z

docs/3. Verification/9.1. yul.md

---
-id: yul
-title: Yul verification
-slug: /yul


we could also add a redirect for yul

manuelwedler · 2026-01-26T12:22:27Z

docs/4. repository/index.mdx

- **Verifier Alliance Database**: Shared database with other verification services. See the [Verifier Alliance](https://verifieralliance.org/) website for more info.
- **BigQuery**: For convenience, the Sourcify dataset is uploaded to [BigQuery](/docs/repository/sourcify-database/#bigquery-datasets).
- **IPFS**: The sources of all verified contracts are pinned on [IPFS](/docs/repository/file-repositories/#ipfs).


I'd like to mention the Verifier Alliance and that we pin to IPFS somewhere. Not sure what would be the best place for these. Maybe new subpages in "Sourcify in depth"?

manuelwedler · 2026-01-26T12:30:46Z

docs/1. Verify on Sourcify/1. What is source code verification.md

+```
+
+<div style={{textAlign: "center", fontStyle: "italic", marginTop: "-0.75rem", marginBottom: "1rem", fontSize: "0.9rem"}}>
+  How a contract looks like on Ethereum - <a href="https://holesky.otterscan.io/address/0x7ecedB5ca848e695ee8aB33cce9Ad1E1fe7865F8/contract">0x7ecedB5ca848e695ee8aB33cce9Ad1E1fe7865F8</a> on Ethereum Holesky Testnet


Suggested change

How a contract looks like on Ethereum - <a href="https://holesky.otterscan.io/address/0x7ecedB5ca848e695ee8aB33cce9Ad1E1fe7865F8/contract">0x7ecedB5ca848e695ee8aB33cce9Ad1E1fe7865F8</a> on Ethereum Holesky Testnet

How a contract looks like on Ethereum - <a href="https://eth-holesky.blockscout.com/address/0x7ecedB5ca848e695ee8aB33cce9Ad1E1fe7865F8?tab=contract">0x7ecedB5ca848e695ee8aB33cce9Ad1E1fe7865F8</a> on Ethereum Holesky Testnet

the otterscan link is down

kuzdogan · 2026-01-26T13:07:57Z

docs/1. Verify on Sourcify/3. Verify via Remix.md

+title: Verify via Remix
+---
+
+You can use the "unified verification plugin" written by the Sourcify team to verify on multiple verifiers on Remix.


Suggested change

You can use the "unified verification plugin" written by the Sourcify team to verify on multiple verifiers on Remix.

You can use the ["Unified Verification Plugin"](https://github.com/remix-project-org/remix-project/tree/master/apps/contract-verification) written by the Sourcify team to verify on multiple verifiers on Remix.

kuzdogan · 2026-01-26T13:08:34Z

docs/1. Verify on Sourcify/4. Verify via Hardhat.md

+```js title="hardhat.config.js"
+sourcify: {
+  enabled: true,
+  // Optional: specify a different Sourcify server
+  apiUrl: "https://sourcify.dev/server",
+  // Optional: specify a different Sourcify repository
+  browserUrl: "https://repo.sourcify.dev",
+}
+```


Wasn't this enabled by default?

We also have different v2 and v3 commands on our main page. How does it relate to this?

kuzdogan · 2026-01-26T13:10:14Z

docs/1. Verify on Sourcify/6. Verify via API.md

Let's change "Verify via API" to "Verify via Sourcify API" (just the file name and title, not the slug)

kuzdogan · 2026-01-26T13:13:59Z

docs/1. Verify on Sourcify/8. Supported languages.md

+| Language | Supported | Exact match support | Monitoring | Metadata/ABI | IPFS data |
+| --- | --- | --- | --- | --- | --- |
+| Solidity | ✅ | ✅ | Similarity and IPFS | Both | ✅ |
+| Vyper | ✅ | ❌ | Similarity | ABI | ❌ |
+| Yul | ✅ | ❌ | Similarity | ❌ | ❌ |


I also don't get the Monitoring: Similarity and IPFS part. This table is a bit confusing overall. I think we can even remove this page completely.

kuzdogan · 2026-01-26T13:42:36Z

I'd say this is a great start and already a big jump, thanks @marcocastignoli !

I just think this probably needs couple more revisions until we get to a shared understanding and structure. But surely no rush here.

I really like the "Verify On Sourcify" section but the following sections didn't fully feel clearly structured. What I suggest now is to add the following pages higher up in the menu into their own pages. Also check the following visit stats of last 30 days:

I suggest we have the following sidebar menu:

Intro
API
Supported Chains
Requesting Chain support
Contract dataset (like in https://docs.sourcify.dev/docs/repository/)
Verify on Sourcify
Sourcify in depth
Integrate Sourcify
Run your instance

Restructure docs to make the right information more easily findable

ca44901

manuelwedler added this to Sourcify Public Jan 20, 2026

manuelwedler moved this to Sprint - Needs Review in Sourcify Public Jan 20, 2026

manuelwedler self-requested a review January 20, 2026 15:52

marcocastignoli self-assigned this Jan 21, 2026

manuelwedler requested changes Jan 26, 2026

View reviewed changes

kuzdogan reviewed Jan 26, 2026

View reviewed changes


		Sourcify ([sourcify.dev](https://sourcify.dev)) is a source-code verification service for Ethereum smart contracts supporting Solidity and Vyper. Sourcify is fully commited to Open-source, Open-data and Open-standards in smart-contract verification instead of siloed, propriety services. We foster these values across the ecosystem and work actively to push the status-quo in this direction.

		Different than other verification services, Sourcify leverages the [Solidity metadata](/docs/metadata/) and its integrity hash to find [exact matches](/docs/exact-match-vs-match/) of Solidity contracts (see [the playground](https://playground.sourcify.dev)).

-lib-sourcify is used to directly verify contracts, it's NOT a wrapper around the Sourcify API. lib-sourcify works also in the browser, allowing source code verification to be executed in the user environment.
+lib-sourcify is used to directly verify contracts, it's NOT a wrapper around the Sourcify API. It supports Node.js and browser environments.
+Applications can integrate lib-sourcify in their frontends. This allows for verifying contract sources on the user's end and minimizes trust towards Sourcify. You can find an example [here](/blog/recap-2025/#lib-sourcify-on-browser-local-verification).

	slug: /signature-database
	slug: /repository/signature-database

	How a contract looks like on Ethereum - <a href="https://holesky.otterscan.io/address/0x7ecedB5ca848e695ee8aB33cce9Ad1E1fe7865F8/contract">0x7ecedB5ca848e695ee8aB33cce9Ad1E1fe7865F8</a> on Ethereum Holesky Testnet
	How a contract looks like on Ethereum - <a href="https://eth-holesky.blockscout.com/address/0x7ecedB5ca848e695ee8aB33cce9Ad1E1fe7865F8?tab=contract">0x7ecedB5ca848e695ee8aB33cce9Ad1E1fe7865F8</a> on Ethereum Holesky Testnet

	You can use the "unified verification plugin" written by the Sourcify team to verify on multiple verifiers on Remix.
	You can use the ["Unified Verification Plugin"](https://github.com/remix-project-org/remix-project/tree/master/apps/contract-verification) written by the Sourcify team to verify on multiple verifiers on Remix.

Restructure docs to make the right information more easily findable #51

Are you sure you want to change the base?

Restructure docs to make the right information more easily findable #51

Uh oh!

Conversation

marcocastignoli commented Jan 20, 2026

Uh oh!

netlify bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for sourcify-docs ready!

Uh oh!

manuelwedler commented Jan 26, 2026

Uh oh!

manuelwedler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kuzdogan commented Jan 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

netlify bot commented Jan 20, 2026 •

edited

Loading