By Mehdi HassanWhat should an open source project website include?
An open source project website should include what the project does, how to install it, a short working example, links to docs and the repository, community proof, a contributing path and the license. If a company sells a hosted or enterprise version, the site also needs a clear explanation of the commercial tier.
The website has to serve three audiences at once: users evaluating the project, contributors looking for a way in, and, for commercial open source (COSS) companies, buyers deciding whether to pay. Our developer tools website design hub covers the wider principles; this page is about the open source version of the problem.
Audience | What they want first | Where it goes |
|---|---|---|
New user | What it does, install, example | Homepage hero and quickstart |
Experienced user | Docs, changelog, upgrade notes | Docs and release pages |
Contributor | How to help, where to talk | Contributing page, community links |
Buyer (COSS) | What paid adds, pricing, support | Cloud or enterprise page, pricing |
Sponsor | How to fund the project | Sponsor page or section |
When should a GitHub README become a real website?
A README should become a real website when it's trying to do too many jobs: docs, marketing, community and a sales pitch for a hosted version. When the README needs a table of contents to navigate, or when you're launching a commercial tier, it's time.
Keep the README after you launch the site. It should stay short: a description, install, a minimal example, a link to the docs site and badges for build status and license. The website takes over the longer jobs. Many projects start with a single landing page plus a docs site, which is often enough; our comparison of landing pages, microsites and websites helps decide how much you need.
What goes on the homepage of an open source website?
The homepage of an open source website should show what the project does in one line, the install command, a short example and two clear actions: read the docs and view on GitHub. In open source, the install command is the call to action.
- One-line description. The job, the language or ecosystem, and what makes it different.
- Install command. One line, copyable, with tabs for package managers if you support several.
- Example. The smallest code sample that shows the point, matching the docs quickstart.
- Actions. "Get started" to the docs and "Star on GitHub" to the repo.
- Who uses it. Logos or a short list of known projects using it, with permission.
- Community. Links to chat, discussions and the contributing guide.
How should an open source site show stars and contributors?
An open source site should show stars, contributors and release activity as live, verifiable signals, placed near the top but not as the headline. They prove momentum and community health, which is what users weigh when choosing a dependency.
Stars signal interest; contributors and recent releases signal health. A project with steady releases and many contributors is a safer bet than one with lots of stars and no commits this year, and experienced developers know it. Show a contributor avatar wall or count, the date of the latest release and a link to the changelog. If the project has a governance model or foundation, say so; it matters to companies deciding whether to depend on it.
What a contributor path looks like
A contributing page that explains how to set up the project locally, how to run tests, the code style, how pull requests are reviewed and the code of conduct.
Link to issues labelled for first-time contributors, the community chat or discussion forum, and any regular community calls. Name the maintainers so newcomers know who reviews their work. A short "what we need help with" section turns interested visitors into contributors faster than a generic invitation.
How should a COSS company present its commercial tier?
A commercial open source company should present its paid tier on its own page, say plainly what stays free and open forever, and explain what the paid version adds: hosting, scale, security features, support or compliance. Ambiguity about the license or the free tier is what open source users punish most.
Separate the paths
Keep the project homepage about the project. Add a clear Cloud or Enterprise link in the navigation that leads to the commercial pages.
State the open core
List what's in the open source project, under which license, and commit to it in writing.
List what paid adds
Managed hosting, SSO, audit logs, support SLAs, compliance. Be specific and honest.
Compare self-host and hosted
A table of what each option costs you in time and money, without disparaging self-hosting.
Publish pricing
Show the hosted tiers and limits. See our guide to devtools pricing pages.
How should an open source project handle docs and design?
An open source project should host docs on the website with search, versioning and a quickstart that matches the homepage, and give the project a simple, consistent visual identity. Docs are where users spend most of their time, so they deserve as much care as the homepage.
Our guide to developer documentation site design covers search, quickstarts and versioning. For identity, a wordmark, a small palette and a well-designed code block style go a long way; open source communities tend to distrust heavy corporate branding. Devtools branding covers how to look considered without looking like marketing, and the developer tool landing page examples include several open source projects worth studying.
How much does an open source project website cost?
An open source project website can cost nothing if a maintainer builds it with a docs framework, or a few thousand dollars and up for a designed and written site. Typical landing page quotes range widely, and a COSS company launching a commercial tier usually needs more than a template.
Our landing page cost guide breaks down typical market ranges. If your project already has a site but the homepage is the weak point, a homepage-only redesign is often enough.
