Skip to main content

How to contribute to the developer portal

We wanted to build a developer portal as open and inclusive as Cardano - a portal in the hands of the Cardano community that can be constantly evolved by it.

Why Contribute?​

Build Your Resume​

Each contribution you make acts as a precious notch on your belt towards career development or job searches within the Cardano ecosystem. It is also a way for people to find examples of your work and verify your abilities. By contributing to open source projects, you will not only gain a lot of valuable experience, but if your profile reaches a certain level of attention and recognition, you are also more likely to get professional opportunities further down the line.

Build Your Reputation​

Contributions to the developer portal will give your GitHub name and profile higher visibility as more and more people come across your work online. As visibility increases, so too will the reputation of your name and brand.

Build Your Confidence​

Creating tutorials and showing fellow community members how to create will not only elevate your knowledge of your own skills and processes, but will also bestow you with greater confidence in your abilities as you interact with others.

Since everything is public, people typically pay greater attention to how well something is written or programmed. This will afford you with an invaluable set of eyes on your contributions that will serve as a crucial peer-reviewed tool to catch errors and refine your work.

Quick Contributions​

Fix typos, update links, small edits:

  • Use GitHub's web editor directly on any file
  • Click the pencil icon ("Edit this page") at the end of any page
  • Make your changes and submit a pull request

Report issues or suggest improvements:

Spread the word:

  • Link to the Cardano Apps when someone asks about projects built on Cardano
  • Share the Builder Tools page with developers looking for SDKs and libraries

Add Your Tool​

General Submitter Requirements​

For all tool submissions:

  • Your GitHub account ideally should have some contribution history or be known in the Cardano community
  • Brand new GitHub accounts may face additional scrutiny
  • All submissions must pass yarn build without errors before submission

Add to Builder Tools​

Builder Tools is a curated directory, not a database. The goal is to keep it as useful as possible for any Cardano developer, which sometimes means maintainers declining a tool that works but isn't the right fit yet. The points below are what maintainers look for, not a checklist you tick to earn a spot.

It's a list of things you build Cardano applications with: SDKs and libraries, APIs and providers, indexers and data infrastructure, node and operations tooling, wallets and connectivity, developer environments, and testing tools. End-user applications (wallets as products, dApps, DEXes, marketplaces, games) belong on cardano.org/apps, not here.

Mostly it comes down to signal. A tool that's genuinely useful, novel, or has gained real community adoption usually carries enough signal for maintainers to recognize it and say yes. A tool that works but hasn't found meaningful adoption, or isn't yet relied on by larger projects and applications, often hasn't generated that signal. That's not a no forever; things stand the test of time, so keep iterating and traction tends to show.

Cardano is a vast sea of open-source repositories that work together, and a directory listing every one-off tool would point developers in every direction at once. So if you've built something niche for a specific workflow, the strongest move is often to contribute it into one of the established repositories already serving that domain, where it reaches more developers and is maintained alongside the rest. A tool built for one specific need, even a quick one-off that does exactly what it claims, isn't always enough on its own.

Open source is encouraged (set repository); hosted and closed services are welcome too (repository: null).

The mechanics — the exact entry format, field conventions, validation, and PR flow — live in CONTRIBUTING.md. In short: add your entry to the end of the BuilderTools array in src/data/builder-tools/tools.js, pick exactly one category and the language/interface properties from tags.js, run yarn build (it validates your entry), and open a pull request with the "Add Builder Tool" template. If your tool reads, serves, or indexes chain data, or runs/talks to a node, the next section helps pick the right category layer.

How the data & node categories relate​

If your tool reads, serves, or indexes chain data, or runs/talks to a node, it sits at one layer of a stack. Pick the layer the tool operates at:

  • node (Nodes & Clients) - the node software itself: run or be a node (a full node, an alternative client implementation, an L2 node).
  • node-access (Node Access & RPC) - talk to a node: RPC bridges and protocol libraries that expose a node you run.
  • indexer (Indexers & Data) - self-host a queryable store: ingest chain data and serve it back (full indexers, lightweight indexes, data nodes, streaming pipelines).
  • api (APIs & Providers) - hosted: a managed endpoint you call, with no infrastructure to run.

sdk (SDKs & Libraries) sits across the top: a library that wraps the node-access / indexer / api layers so you build from code.

Rules of thumb: do you call a hosted endpoint (api) or run it yourself (indexer)? Does the tool build its own queryable data store (indexer) or just relay the node's protocol (node-access)? Is it the node itself (node) or something that talks to one (node-access)?

Curation and removal​

The list is curated and pruned, not append-only, so it stays useful over time. Maintainers remove a tool when it stops serving developers. What usually prompts that:

  • the website is down, or the source repository is archived or unreachable,
  • a long stretch (roughly two years or more) with no commits, releases, or community activity and no sign of life,
  • it's been superseded by a better-maintained tool for the same job,
  • a hosted service that's been discontinued,
  • an end-user application that belongs on cardano.org/apps,
  • or it no longer meets a basic quality and trust bar.

These are signals, not a scorecard. Maintainers weigh them with judgment and often talk through borderline cases. A removed tool can come back any time through the normal submission, which is also a good moment to refresh its information; a past listing isn't a fast-track.

Maintainer picks​

A few tools carry a maintainer pick (the star): a steer toward what a developer should reach for in a given area today. It's a curated call, not a popularity contest.

  • It leans on signals (registry downloads, recent activity, maintenance, real-world fit) weighed with judgment. Stars alone mislead; a legacy tool often out-stars its maintained successor.
  • Roughly one clear leader per category, a couple more where it's genuinely warranted, and none where nothing stands out.
  • Maintainers choose the picks, so don't set maintainerPick on your own submission.

If you think something deserves a pick, open an issue and make the case: which category it leads, and why.

FAQ​

Q: I don't know how to use GitHub or run yarn build. Can I still contribute?

A: Yes! You can:

Q: How long does it take for my tool to be approved?

A: Pull requests require 3 reviewer approvals. This typically takes a few days to a week, depending on reviewer availability. After approval, changes are merged to the staging branch first (visible at staging-dev-portal.netlify.app), then later pushed to production. This process causes a small delay between staging and production deployment.

Q: Can I update my tool information later?

A: Yes! Submit a new pull request with the updates to your tool entry.

Q: Why was my tool rejected?

A: Common reasons for rejection include:

  • Domain issues - Using temporary hosting domains, URL shorteners, or unstable domains
  • New GitHub account - Submitter account lacks contribution history or community recognition
  • Incomplete submission - Missing required fields, broken links, or build errors
  • Marketing-focused description - Using claims like "the best," "the first," or "the only"
  • Out of scope, or not enough signal yet - an end-user app (belongs on cardano.org/apps), or a tool that works but hasn't yet found the adoption that earns a spot. This isn't a permanent no; tools can earn a place as they gain traction.

If your submission was rejected, reviewers will typically provide specific feedback in the pull request comments.

Q: Should I commit yarn.lock changes?

A: No, never commit yarn.lock changes. This file is managed by maintainers. If some slipped into your branch, the CONTRIBUTING FAQ has the exact commands to revert them.

For more details on the GitHub workflow, see CONTRIBUTING.md.

Add a dApp Template or Contract​

Two more curated surfaces live under /templates:

  • App starters are runnable front-end dApp projects you scaffold in one command. To add one, follow examples/templates/README.md.
  • The contract library is a use-case index (escrow, vesting, HTLC...) that links out to on-chain and off-chain implementations. To add an entry, follow src/data/contracts/README.md.

Both are curated like Builder Tools: canonical and maintained, pointing at the established source rather than forking code into the portal. Each entry is validated by yarn build, and the same submitter requirements and review process above apply.

Contributing Documentation​

For content writers and developers who want to work on documentation, blog posts, or improve existing content.

Local Development Setup​

Follow the local development setup in the README: fork, clone, yarn install, yarn build, yarn start. It requires Node.js 22 (the pinned version lives in .nvmrc, so nvm use picks it up) and Yarn 1.20+.

Development vs Production
  • yarn start - Fast development with some limitations (blurry images, search issues)
  • yarn build - Full production build required before submitting PRs

Both commands first run two generators: scripts/generate-stats.js (writes static/stats.json) and scripts/generate-og.js (renders the social-preview cards). Their output is gitignored - never commit it.

Project Structure​

developer-portal/
├── docs/              # Documentation content (images co-located in img/ folders)
├── blog/              # Developer blog posts (tags.yml defines allowed tags)
├── examples/          # Runnable example projects (dApp starter templates)
├── src/data/          # Site data: builder-tools, templates, contracts, navbar, footer, redirects
├── static/img/        # Site-owned assets, grouped by consumer (home, blog, tools, brand, og)
├── plugins/           # Custom Docusaurus plugins
├── scripts/           # Build helpers (stats, social cards, llms.txt paths)
├── sidebars.js        # Navigation structure (hand-authored)
└── docusaurus.config.js

Key locations:

  • /docs/ - All documentation content
  • /src/data/builder-tools/tools.js - Developer tools data
  • /sidebars.js - Controls documentation navigation

Writing Content​

Formatting: See Style Guide for Markdown syntax and Docusaurus components.

Essential rules:

  • Pages are .md files - Docusaurus components (Tabs, DocCardList) work inside .md, so never create .mdx
  • A new page needs a manual entry in sidebars.js; navigation is hand-authored (no _category_.json files)
  • Doc images live next to the page in an img/ folder, referenced relatively (./img/name.png)
  • Use ## Level 2 headings as top-level (page title is auto-generated)
  • Include frontmatter with id, title, description
  • Test with yarn build before submitting

Troubleshooting​

Node.js version error: [ERROR] Minimum Node.js version not met Solution: Use Node.js 22. With nvm installed, nvm use in the repo root switches to the version pinned in .nvmrc.

More Ways to Contribute​

Improve Text Content​

Fix typos and improve texts, especially if you are a native speaker and have strong writing skills.

Create Graphics​

If you are a talented graphic designer, you can improve various charts and diagrams. We should always use graphics that work well in both light mode and dark mode for the portal. You can also make one graphic for each.

Blog Contributions​

When contributing blog posts, please follow these guidelines:

Tag naming conventions:

  • Use lowercase tags only (e.g., ai, defi, dex, dao)
  • Tags must be defined in blog/tags.yml before use
  • Check existing tags in blog/tags.yml before adding new ones

Truncation markers:

  • Most blog posts should include <!-- truncate --> markers for better previews
  • Exception: Posts tagged with media (short video content) should NOT include truncation markers to preserve video visibility in blog listings

Social cards:

  • The preview image shown when a post is shared on social media is generated at build time from the post title. You do not need to make one.
  • Do not add an image: field to the frontmatter. Every post gets a generated card, so the field is ignored.
  • The same applies to documentation pages: scripts/generate-og.js renders a branded card for every doc and site page during the build.

Review Pull Requests​

If you have excellent technical understanding and mistakes catch your eye, you can review pull requests. You should have made contributions before and have a GitHub account with some reputation. If you are unsure about if you are a good fit, participating in the active discussions that take place in developer portal github issues/pull requests is always a good place to start to have your name visible.

Getting Help​