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	`50e6bf1`
🔍 Latest deploy log	https://app.netlify.com/projects/sourcify-docs/deploys/698dea60fe843c0008bfcc5f
😎 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 :)

docs/0. Intro.md

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

docs/3. Verification/9. vyper.md

docs/3. Verification/9.1. yul.md

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"?

I added a new page 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/5. 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?

@manuelwedler do you have a better overview about this?

This is still for hardhat v2. I said earlier, I'd rather get this PR merged now and adapt the hardhat and foundry commands as part of argotorg/sourcify#2589

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

the one on the homepage for v2 is the same, we only show the option to change urls here, but we don't need to actually.

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

docs/5. Verify on Sourcify/6. Verify via Sourcify 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

manuelwedler · 2026-02-05T10:53:36Z

@marcocastignoli I made some changes to the parquet download docs on branch main. Please make sure these changes won't be lost here

kuzdogan

Lovely <3 I think this is good to go. Just one wrong information corrected in the monitor docs. I'll also just suggest we rename "Integrate Sourcify" to "npm libraries" or something else if you can think of a better name. "Integrate" is a bit vague. But not a strong opinion.

docs/6. Sourcify in depth/7. Monitoring service.md

Co-authored-by: Kaan Uzdoğan <kaanuzdogan@gmail.com>

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

marcocastignoli moved this from Sprint - Needs Review to Sprint - Up Next in Sourcify Public Feb 2, 2026

marcocastignoli moved this from Sprint - Up Next to Sprint - In Progress in Sourcify Public Feb 12, 2026

marcocastignoli added 3 commits February 12, 2026 14:22

Address PR comments

17aab62

Merge remote-tracking branch 'origin/main' into restructure-docs

2863d76

Add new page "Storage Services" in Sourcify in depth

c76f1e3

kuzdogan approved these changes Feb 12, 2026

View reviewed changes

docs/6. Sourcify in depth/7. Monitoring service.md Outdated Show resolved Hide resolved

marcocastignoli and others added 2 commits February 12, 2026 15:29

Update docs/6. Sourcify in depth/7. Monitoring service.md

41881fb

Co-authored-by: Kaan Uzdoğan <kaanuzdogan@gmail.com>

Rename integrate sourcify to Npm libraries

50e6bf1

marcocastignoli merged commit b790cdd into main Feb 12, 2026
3 of 4 checks passed

github-project-automation bot moved this from Sprint - In Progress to Sprint - Done in Sourcify Public Feb 12, 2026

marcocastignoli deleted the restructure-docs branch February 12, 2026 14:58

kuzdogan moved this from Sprint - Done to COMPLETED in Sourcify Public Feb 12, 2026

-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

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!

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!

Uh oh!

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!

manuelwedler commented Feb 5, 2026

Uh oh!

kuzdogan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

netlify bot commented Jan 20, 2026 •

edited

Loading