# bitcoincore.org: the Jekyll site behind Bitcoin Core's documentation > The bitcoincore.org repository is the source of the Bitcoin Core project website, a Jekyll build with a strict multilingual front matter contract and a test suite that checks rendered HTML, internal links and binary download URLs. It is MIT licensed, and its main value to an engineer is as the place where release notes and the download page live. **bitcoin-core/bitcoincore.org** — Bitcoin Core project website - Repository: https://github.com/bitcoin-core/bitcoincore.org - Website: https://bitcoincore.org/ - Stars: 776 · Forks: 537 - Language: HTML - License: MIT - Published: 2026-10-21 · Updated: 2026-10-21 · Language: en - Canonical page: https://hysenlabs.com/projects/bitcoin-core-bitcoincore-org ## The website is the product, and the content is the point The repository is the source code of the Bitcoin Core project website built with Jekyll, and it is one of the more consequential websites in the ecosystem, because it is where the download links and the release notes live. That last detail is easy to overlook when you look at the repository as a Jekyll site. A user who wants to verify a Bitcoin Core binary does not read a git tag, they open the download page, and that page is generated from this repository. The Makefile in the repository has a test target that checks the links on the /en/download page point to the separately stored binaries in /bin, which is a direct statement that the page and the binaries are kept in step deliberately. The directory structure is organised around the content type and the language. The README describes _posts//posts for blog articles, _posts//pages for static pages, and _posts//releases for Bitcoin Core release notes. The top level entries show the same idea in the actual layout, with _posts, _releases, _layouts, _includes, _data, _sass, _plugins, _doc, assets and the en directory, plus a .well-known directory for site metadata and a logs directory. The primary language of the repository is HTML, which is what you would expect for a site rather than an application, and the licence is MIT with LICENSE and COPYING both present at the root. There are no GitHub releases, which is consistent with the nature of the artefact. The releases here are the Bitcoin Core release notes, published as pages in the site, not as repository tags. ## The front matter contract that every translation must satisfy The most useful part of the README for a contributor is the front matter section, because getting it wrong is the most common way to fail the build. The front matter is required for the multilingual setup in all files, and six fields are required. The name field is the group name for a unique article, and each translation must share the same group name, for example october15-report. The id field must be unique per article translation, using the language code plus the name, for example en-october15-report. The permalink must include the language code and end with a trailing slash, for example /en/2015/12/31/report/. The title is the translated title of the article. The type is the content type, such as pages, posts, releases or meetings. The layout is the layout template, such as page or post. The lang is the language code, such as en or fr. A complete example from the README: ```yaml --- title: Short Title name: short-title layout: post type: posts lang: en id: en-short-title permalink: /en/2016/01/01/short-title ``` The file naming rule is separate from the front matter and just as strict. File names must be in the format Y-m-d-title.md, for example 2015-12-31-title.md, and file names can be translated. The group name and the id together are what make translation work. The name field ties the translations of one article together as a group, and the id field gives each language its own unique identifier and its own permalink. A translator adds a file in their language directory with the same name field, a new id prefixed with their language code, and a permalink under their language prefix. The rest of the site machinery handles the rest. The translation process itself is documented in CONTRIBUTING.md, which the README links from the Translations section. ## Building the site locally with Jekyll and Ruby The build path is documented in enough detail to run it without guessing, and it is a standard Jekyll setup with a Ruby version constraint. You need Ruby 3.1.2, installed using system packages, rvm, rbenv or another method. There is a .ruby-version file at the repository root that pins the version for version managers. An alternative is to use Docker, for which instructions are available under contrib/devtools/. Then clone the repository and change directory into it: ```bash git clone https://github.com/bitcoin-core/bitcoincore.org.git cd bitcoincore.org ``` The Ruby packages come next. The README is explicit about the two different privilege situations, which is a small thing that saves a confusing error. You install the bundle utility using the Ruby package manager gem, and then use bundle to install the rest of the Ruby packages needed to build the site. Depending on your system configuration, you may need to run gem as the superuser by putting sudo followed by a space before the gem command, and you should not need to use sudo with the bundle command. ```bash gem update --system gem install bundler bundle install ``` To preview the site, which launches a tiny webserver on port 4000: ```bash bundle exec jekyll server --future ``` And to build the site, with the output placed in the _site directory: ```bash bundle exec jekyll build --future ``` The --future parameter is only required if you are adding any pages dated in the future, such as prepared release announcements. That is a detail specific to how Bitcoin Core does release communication, and it explains why the parameter appears in every command in the README and in the Makefile. ## The test suite checks rendered HTML, internal links and binaries The test suite is the part of this repository that a contributor should care about most, because it encodes what the site must not get wrong. The Makefile splits the tests into a fast and a slow target, and the build target depends on both. The slow target checks for malformed HTML and broken internal links using htmlproofer with the external links disabled and a URL ignore pattern for paths under /bin, and then runs a separate script, contrib/qa/test-binary-availability.sh, to check that the links on the /en/download page point to the separately stored binaries in /bin. The fast target does two grep based checks over the built HTML. The first looks for broken Markdown reference-style links that are displayed in the text unchanged, for example a link written as [broken][broken link], and the second ensures that no template strings leak through liquid rendering. The README gives the equivalent commands directly, and the additional parameters to jekyll build ensure that all possible pages are built and checked: ```bash bundle exec jekyll build --future --drafts --unpublished bundle exec htmlproofer --check-html --disable-external --url-ignore '/^\/bin/.*/' ./_site ``` The Makefile's build target adds two flags the README command does not: --strict_front_matter, which is what enforces the front matter contract described earlier, and --incremental on the preview target so a local serve loop stays fast. The preview target therefore runs jekyll serve with --future, --drafts, --unpublished, --incremental and --strict_front_matter, and every build starts with jekyll clean so a stale _site never leaks into the test run. The design is sensible for a site where a wrong link on the download page is a security problem. If a user follows a download link that points somewhere they did not expect, the consequences are not a broken page, they are a compromised wallet. ## The Minimal Mistakes theme, and the documentation caveat that comes with it The website uses an old version of the Minimal Mistakes theme, and the README links to that theme's documentation for configuration variables, creating pages and posts, and adding new JavaScript. Then comes the caveat, and it is the kind of warning that saves hours: current documentation may describe features not available in the old version of the theme used by the website. The theme's own documentation is a moving target, and the site is pinned to an older revision of it. That is the central tension in this repository. The site needs a stable, known-good theme so that a rebuild never changes the output of a page that people rely on, such as the download page. The cost is that the theme's documentation drifts ahead of what the site can actually do, so a contributor following the upstream guide will sometimes try a feature that does not exist here. In practice the route is: read the site documentation, check the theme's own repository for what the pinned version supports, and treat the upstream docs as a reference for the ideas rather than the API. The rest of the layout supports the content model. There is a _data directory for the data files Jekyll uses to drive navigation and other site data, _includes and _layouts for the templates, _plugins for custom Liquid behaviour, and _sass for the styles. The _releases directory sits at the top level alongside _posts, and the en directory holds the English specific parts of the site, which suggests the structure separates language independent content from language specific overrides rather than duplicating everything per language. The Makefile and the _config.yml at the root are the two files a new contributor should read first, because the Makefile encodes the build and test contract and the config declares the collections and defaults the whole site runs on. ## Licence, maintenance and who should care about this repository The licence is MIT, and both LICENSE and COPYING are present at the repository root. For a documentation site that is the least interesting fact, and it is also the fact that means you can fork it and use the structure without worrying. On maintenance, the repository is not archived and the last push was on 2026-10-22. There are no GitHub releases, because the releases here are Bitcoin Core release notes published as site pages, not artefacts in this repository. The audience is narrow and worth stating precisely. There are three kinds of person who should care about this repository. The first is a contributor to the Bitcoin Core project website, which is the common case. The second is a developer who needs to publish a release note or a blog post in one of the many languages the site supports, and who needs to know the front matter contract and the translation process. The third is anyone who wants to understand how a project of this size publishes signed binaries and release notes with a verification step, because the binary availability test is a small piece of engineering that most projects do not bother with. For anyone outside those three groups, the value is mostly as a reference implementation. A multilingual Jekyll site with a strict front matter contract, a fast and slow test split, and a link checker that refuses to let a download page drift from the artefacts it points at is a decent template for a project site that people will actually depend on. If you do want to contribute, the README is direct about it. Contributions are welcome and the details are in CONTRIBUTING.md, and the translation process section of that file is the one to read first if your contribution is a translation rather than a new page. One practical note for a first contribution. The build and test cycle needs a working Ruby toolchain and a bundle install, and the slow test downloads and checks external binaries, so the first run is slower than the edit that prompted it. Get bundle install and a clean build working on an unchanged checkout before you add a page, so a failure later is unambiguously yours. ## Conclusion Adopt this repository if you need to contribute to the Bitcoin Core project website, to publish a release note, or to run the same link and HTML checks locally before opening a pull request. Do not adopt it as a documentation platform for your own project, since the front matter contract and the tooling are specific to this site. Verify first that your Ruby version matches the .ruby-version file, that the front matter fields for the language you are writing in are complete, and that the htmlproofer and binary availability checks pass on your machine before you push. ## FAQ ### What is the bitcoincore.org repository? It is the source code of the Bitcoin Core project website, built with Jekyll. It holds the blog articles, static pages and Bitcoin Core release notes, and the site publishes the download page that points at the signed binaries. ### How do I build the Bitcoin Core website locally? Install Ruby 3.1.2, clone the repository, then run `gem update --system`, `gem install bundler` and `bundle install`. Preview with `bundle exec jekyll server --future`, which serves on port 4000, or build with `bundle exec jekyll build --future`, which writes to the _site directory. ### What front matter fields does a bitcoincore.org post require? Six: name as the group name shared by all translations, id as a unique id using the language code plus the name, permalink including the language code and ending with a trailing slash, title, type such as posts, pages or releases, layout, and lang. ### What does the bitcoincore.org test suite check? The slow target runs htmlproofer for malformed HTML and broken internal links and then checks that the links on the /en/download page point to the binaries in /bin. The fast target looks for broken Markdown reference-style links and for liquid template strings leaking into the rendered HTML. ### Why is the --future flag used when building bitcoincore.org? The README states it is only required if you are adding pages dated in the future, such as prepared release announcements, and the Makefile passes it to every build and preview target for that reason. ### What license is bitcoincore.org released under? MIT, with both LICENSE and COPYING present at the repository root. The repository is not archived and the last push was on 2026-10-22. ## Sources - [bitcoin-core/bitcoincore.org on GitHub](https://github.com/bitcoin-core/bitcoincore.org) - [Issues](https://github.com/bitcoin-core/bitcoincore.org/issues) - [License: MIT](https://github.com/bitcoin-core/bitcoincore.org/blob/master/LICENSE) - [Project website](https://bitcoincore.org/) - [README](https://github.com/bitcoin-core/bitcoincore.org/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bitcoin-core-bitcoincore-org