github/opensource.guide: the Jekyll site behind GitHub's open source handbooks

What github/opensource.guide actually is, and who it is written for

The README opens by describing the project as "a collection of resources for individuals, communities, and companies who want to learn how to run and contribute to an open-source project." That sentence sets the audience precisely: maintainers who are starting a project, contributors who want to understand how a healthy one behaves, and companies that need a shared vocabulary for the open source work their employees do.

The repository is not a tool you install into an application. It is a static site: Jekyll templates in _layouts/ and _includes/, article sources in _articles/, structured content in _data/, and assets/ for the rest. The README states that the guides were created and curated by GitHub with outside community reviewers, and that the goal was to aggregate community best practices rather than GitHub's own opinion. The README also notes the guides are not exclusive to GitHub products, which matters if you are evaluating whether the advice is vendor-neutral enough to cite internally.

If you arrived looking for a package to add to a dependency list, this is the wrong repository. The unit of value here is prose that has been reviewed by named contributors, published at opensource.guide, and versioned in git so you can see how the advice changed over time.

How the Jekyll build turns _articles into the published site

The README states plainly that the site is powered by Jekyll. The repository layout supports that: _config.yml holds site configuration, _articles/ holds the guide content, _layouts/ and _includes/ hold the templates that wrap it, and _data/ holds structured values that pages reference instead of hardcoding. index.html is the entry page, CNAME points the build at the custom domain, and assets/ carries the stylesheets and images.

The dependency story is split across two ecosystems. package.json is marked private and declares only primer-core and primer-marketing at version 7.0.0, both GitHub design-system packages, plus a postinstall step that runs npm install inside test/. Ruby handles the site itself through the Gemfile and Gemfile.lock, with .ruby-version pinning the interpreter and .node-version pinning Node for the asset side.

Testing is wired through npm: the test script in package.json is script/test, and the test/ directory has its own package.json installed by postinstall. CI runs through GitHub Actions, and the README carries a build status badge pointing at the workflow.

Running the guides locally and making your first edit

The README does not print an install sequence. It points at CONTRIBUTING.md for ways to offer feedback and contribute, and that file is where the authoritative steps live. What the repository does show is the toolchain you need: Ruby pinned by .ruby-version, Node pinned by .node-version, Bundler via the Gemfile, and npm for the asset and test dependencies.

The only command the repository files spell out verbatim is the test entry point. package.json defines the test script as script/test, so the command you run from the repository root is:

npm test

That resolves to script/test. The postinstall hook in package.json runs npm install inside test/, so a plain npm install at the root also pulls in the test directory's own dependencies; the README does not document that step in prose, but the script is visible in the file.

For the site itself, the README only says the site is powered by Jekyll and directs contributors to CONTRIBUTING.md. It does not list bundle install, jekyll build, jekyll serve, a port, or any flag. Read CONTRIBUTING.md before scripting a build, and treat the Jekyll defaults as undocumented by this repository. After editing a file under _articles/, the check you can rely on is the one the repository defines: npm test.

Where github/opensource.guide stops being the right tool

The most common mismatch is expecting enforcement. Nothing in the README or the repository layout suggests the guides validate your repository, score your community health, or fail a build when a policy is missing. There is no CLI, no configuration file you point at your own project, and no output artifact other than the generated website. If you need automated checks, this repository is the wrong place to look.

The second limitation is legal. The README carries an explicit disclaimer: "While we've got advice about running an open source project, we're not lawyers." It directs readers to the legal disclaimer in notices.md before acting on the content. Any guide that discusses licensing, contribution terms or governance inherits that caveat, and you should not treat the articles as counsel.

The third is provenance. The README says the guides were created and curated by GitHub with outside reviewers, and that the intent was to aggregate community practice rather than one company's position. That intent is stated, not guaranteed by the build. If your organisation needs a source with no corporate sponsor, this is a sponsored project and you should weigh that yourself.

Finally, the maintenance signal is worth reading literally. The repository is not archived, and the last push was on 2026-10-20. That is recent activity on the repository, but the README does not describe a release process, and the repository has no published GitHub releases. Treat the git history, not a version number, as your changelog.

Alternatives, and what changes when you pick one

The closest alternative in spirit is a general-purpose static site generator paired with your own content. Jekyll is what this project uses, and the README names it directly; swapping in Hugo or Eleventy would mean rewriting the templates in _layouts/ and _includes/ and rebuilding the _data/ references, while keeping the same Markdown articles. You would gain a different build tool and lose the existing theme, the primer-core and primer-marketing styling, and the script/test harness.

A second alternative is a documentation platform rather than a static generator, where content lives in a hosted editor and publishing is a button. That removes the Ruby and Node toolchain entirely, which is the main friction in this repository, but it also removes the git-based review path that CONTRIBUTING.md is built around. For a project whose stated goal is aggregating reviewed community practice, the review path is the point, not an implementation detail.

A third option is to not fork at all and simply link to opensource.guide. The content is CC-BY-4.0, so quoting with attribution is permitted under that licence, and you avoid owning a Jekyll build. You lose local customisation and the ability to add your organisation's own articles to the same site.

Licence, attribution and the cost of keeping a fork current

The README states that content is released under CC-BY-4.0 and points to notices.md for complete details, including attribution guidelines, contribution terms, and software and third-party licenses and permissions. The repository also carries a LICENSE file at the top level. If you republish articles, the attribution guidelines in notices.md are the document to read; CC-BY-4.0 requires attribution, and the notices file is where this project spells out what that means for its content. This is a description of what the files say, not legal advice.

The upgrade cost is not a dependency bump. Jekyll sites age through their gem set, their theme packages and their CI runner image. Here that means the Gemfile and Gemfile.lock on the Ruby side, primer-core and primer-marketing pinned at 7.0.0 in package.json on the Node side, and the GitHub Actions workflow under .github/. A fork inherits all three and has to keep them aligned, because the postinstall hook in package.json installs the test directory's own dependencies, so a Node major change touches two package manifests at once.

The content side is cheaper. Articles are Markdown files in _articles/, and pulling upstream changes is a git operation rather than a migration. The expensive merge is always the templates, not the prose.

Editorial conclusion

Adopt it if you need a citable, CC-BY-4.0 body of open source practice to read, quote or fork into your own handbook, and you are willing to run Ruby, Bundler and Jekyll locally. Do not adopt it if you wanted a linter, a template repository or a policy engine: the repository contains articles, layouts and assets, and the README describes no enforcement of any kind. Before you commit to a fork, open _config.yml and _data/ to see how much of the site is data-driven, read notices.md for the attribution terms, and confirm that script/test passes on your machine.

Frequently asked questions

Official sources

1. github/opensource.guide on GitHub
2. Issues
3. License: CC-BY-4.0
4. Project website
5. README