# jasmine.github.io is the Jekyll site that publishes Jasmine's documentation

> This repository holds the source of the Jasmine documentation site, a Jekyll project with generated API reference sections for the core library, the npm package, the browser runner and the reporters, hand written tutorials, and a small generator called locco that turns side-by-side JavaScript examples into Markdown. It suits a contributor writing Jasmine documentation, and it is not the Jasmine testing library itself.

**jasmine/jasmine.github.io** — Source for Jasmine's documentation

- Repository: https://github.com/jasmine/jasmine.github.io
- Website: https://jasmine.github.io
- Stars: 573 · Forks: 411
- Language: HTML
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/jasmine-jasmine-github-io

## The documentation site, not the testing framework

The repository description is simply the source for Jasmine's documentation, and the README points at the site it builds, jasmine.github.io. The primary language is listed as HTML, which is what a Jekyll site is made of, and the licence is MIT. The default branch is master, the last push was on 2026-08-23, and there are no GitHub releases, which is consistent with a site whose versions live in the published output rather than in tagged releases. The distinction matters if you arrive at the repository expecting the test framework: Jasmine itself is the JavaScript testing library, and this repository is the prose, the examples and the generation pipeline that produce its documentation. The top level listing shows how much is generated. There are separate API sections for the core library in _api/, for the npm package in _npm-api/, for the browser runner in _browser-runner-api/ and for the reporters in _reporters-api/, alongside a _upgrade-guides/ directory, a _faq/ directory, _tutorials/, _layouts/, _includes/, _plugins/, pages/, css/, images/, scripts/, setup/, src/ and examples/. The site also ships a 404.html, a favicon and an index.html at the root.

## Setting up a local copy

The contributing instructions are precise about the order. You fork the repo, create a feature branch with git checkout -b my-new-docs, ensure ruby and bundler are installed with gem install bundler, install the Ruby dependencies with bundle, or with bundle install --path vendor/bundle to keep them in the local folder instead of installing them globally for the system, and install the JavaScript dependencies with npm install. The repository carries a .ruby-version file, which pins the Ruby version the project expects, a Gemfile and Gemfile.lock for the Ruby side, and a package.json and package-lock.json for the Node side. The npm side is small. The dependencies are anchor-js for the anchor links, jsdoc for generating the API reference, and yaml. The dev dependencies are jasmine itself, marked, and mustache, which the tutorial generator uses. The package.json also has an install script that copies node_modules/anchor-js/anchor.min.js into scripts/anchor.min.js, which is a small detail that explains why the install hook exists rather than a plain install.

## The generated sections and the rule for editing them

The README is emphatic about which parts of the tree you must not touch by hand. Everything under _api, _npm_api, and _browser-runner-runner-api is auto-generated, and a few of the _tutorials/*.md files are also generated. The ones that are auto-generated have a comment near the top saying what they were generated from, and the instruction is direct: do not edit those files directly, as any changes you make to them will be lost the next time the documentation is generated. This is the single most useful thing to know before contributing, because the API reference is the largest part of the tree and a natural place to start editing. The generated API content comes from JSDoc comments in the Jasmine source itself, which is why the pipeline has to fetch a copy of Jasmine before it can rebuild the reference. The four jsdoc configuration files at the root, jsdoc-conf-core.json, jsdoc-conf-npm.json, jsdoc-conf-browser-runner.json and jsdoc-conf-reporters.json, each describe one of those API sections, and the scripts directory holds the JSDoc plugins that extend the output.

## The rake tasks that regenerate the API reference

The regeneration step is driven by rake tasks, and the README says to run npm run jsdoc to update the API documentation. The package.json script fans out into four, one per API surface.

```bash
npm run jsdoc
```

Underneath, the npm scripts call jsdoc with the matching configuration file, for example jsdoc -c jsdoc-conf-core.json --verbose, and each of the four runs with --verbose. Before that, the local copies of Jasmine have to be brought up to date, and the README names four rake tasks for that: bundle exec rake update_edge_jasmine, bundle exec rake update_edge_jasmine_npm, bundle exec rake update_edge_jasmine_browser, and bundle exec rake update_edge_reporters, to be run as appropriate. The edge naming is deliberate. The edge build is the unreleased version of Jasmine, and the API reference for it is generated first, then copied into a version specific directory when a new version is published. The publishing section explains that step: you copy the edge docs to the new version for each package, for example cp -r _api/edge _api/4.4, and archive the oldest non-archived version by adding archived: true to the relevant global.html, Jasmine.html, module-jasmine-browser-runner.html and index.html files, which removes that version from the listing on the docs home page while leaving it published at the same URLs and reachable through the Archived Documentation link.

## Tutorials, side-by-side examples and locco

The tutorials come in two forms and each has its own authoring workflow. A regular tutorial is a new .md file in _tutorials/ with YAML front matter following the pattern of the other files in that directory, followed by content in HTML and/or Markdown. A side-by-side tutorial is a new .js file in _tutorials/src with mixed doc comment blocks and code, following the pattern of the other sources there, and after adding a configuration for it to locco.js you run the generator.

```bash
node locco.js
```

The README is clear that in the side-by-side case you must check in both the JavaScript source in _tutorials/src and the generated Markdown in _tutorials, since the generator output is part of the repository. In both cases you then have to add a link to your new tutorial manually to pages/docs_home.html, which is a manual step the tooling does not do for you. Archiving an old tutorial is a two step edit: add archived: true to the YAML at the top of the tutorial's Markdown file, and add a link to the tutorial to pages/archives.html. The _api section also carries an archived flag convention, mentioned above, which removes an entry from the version listing without unpublishing it.

## Testing your changes and previewing locally

The preview step is one command, and the Rakefile at the repository root defines it.

```bash
bundle exec rake serve
```

The order the README gives is: update the local copies of Jasmine with the appropriate rake tasks, run npm run jsdoc to update the API documentation, then regenerate the tutorials with node locco.js, and only then preview with bundle exec rake serve. That order matters because the generated API pages are inputs to the site build, and the tutorials are generated from their JavaScript sources. Once you are happy, the submission steps are a commit with git commit -am 'Add some docs', a push to the branch with git push origin my-new-docs, and a pull request. The README also describes the examples/ directory as raw JavaScript examples of Jasmine tests, which it notes are rare, and the listing confirms it with example folders for module mocking, node strip types, react in browser and react in node.

## Providing a live demo for reviewers

For complicated or potentially controversial documentation changes, the README suggests giving the reviewer something to compare against the production site. The setup is a branch and a GitHub Pages setting. In your local fork you create the gh-pages branch from master with git checkout master, then git checkout -b gh-pages, then git push -u origin HEAD. You then enable GitHub Pages for the fork by opening the fork's Settings, selecting Settings -> GitHub Pages and setting Source to the gh-pages branch, and after the page reloads and a few minutes pass you have a personal live demo under your own github.io address. To update what the demo shows you reset the branch to your work: git checkout gh-pages, git reset --hard my-complicated-change, git push -f. The warning in that section is the one that matters in practice, since the force push rewrites the published demo branch, and the reset discards whatever was on it. The README notes that after pushing you wait a few minutes and the live demo shows your changes, and that you can then include the link in the pull request.

## Where jasmine.github.io is the wrong repository

Four limits are worth naming. The first is the obvious one: if you want to use Jasmine, install the framework, and this repository does not contain the test runner. The second is that the site is not a static snapshot you can read without building it. The API reference is produced by running JSDoc over source comments fetched from the Jasmine packages, so an offline reader sees generated files that describe the source rather than the source itself, and a contributor needs the Ruby and Node toolchain in place before they can see a change. The third is the generated file trap, which is worth restating because the API reference is the largest and most attractive part of the tree to edit. An edit to a generated file is not an edit, it is a change that will disappear, and it will do so at the next regeneration, which for a maintainer is a silent loss. The fourth is the version matrix. The site publishes several versions at once, with edge as the unreleased one and each released version in its own directory, and archiving is done by editing a flag in several places at once, so a contribution that touches one version directory can leave the listing inconsistent with the published URLs. The realistic alternative for most readers is the published site at jasmine.github.io, which needs no build at all, and for contributors who only need to fix a page, a direct pull request against the hand written Markdown in _tutorials/ with no regeneration step, since the README's own warning shows that touching the generated paths is the fastest way to lose work.

## Conclusion

Adopt this repository if you intend to contribute documentation to Jasmine, because it holds the only source for the site at jasmine.github.io, including the hand written tutorials, the FAQ pages and the layout of the API reference. Do not adopt it if you are looking for the Jasmine testing framework itself, since this is the documentation site and the library lives elsewhere. Verify two things before you change anything: which files are generated and which are not, because everything under _api, _npm-api and _browser-runner-runner-api is auto-generated and your edits will be overwritten, and which Jasmine version your change targets, because the API reference is published per version with older copies kept in their own directories. The practical first step is to fork the repository, run bundle and npm install, then run bundle exec rake serve to see the site locally before you edit a single page.

## FAQ

### What is the jasmine.github.io repository?

It is the source for Jasmine's documentation site at jasmine.github.io, a Jekyll project with hand written tutorials, FAQ pages, layouts and generated API reference sections for the core library, the npm package, the browser runner and the reporters. It is MIT licensed and is not the Jasmine testing framework itself.

### How do I set up a local copy of the Jasmine documentation site?

Fork the repo, create a branch with git checkout -b my-new-docs, make sure ruby and bundler are installed with gem install bundler, install the Ruby dependencies with bundle or bundle install --path vendor/bundle to keep them local, and install the JavaScript dependencies with npm install. Then run bundle exec rake serve to preview the site.

### Which files in jasmine.github.io must not be edited by hand?

Everything under _api, _npm_api, and _browser-runner-runner-api is auto-generated, as are a few of the _tutorials/*.md files, whose generated ones carry a comment near the top saying what they were generated from. The README warns that changes to those files are lost the next time the documentation is generated.

### How is the Jasmine API reference regenerated?

First update the local copies of Jasmine with the rake tasks update_edge_jasmine, update_edge_jasmine_npm, update_edge_jasmine_browser and update_edge_reporters, then run npm run jsdoc, which fans out into a jsdoc run for the core, browser runner, npm and reporters sections using their respective jsdoc-conf-*.json configuration files. Tutorials are then regenerated with node locco.js.

### How do I add a new tutorial to the Jasmine documentation?

For a regular tutorial, add a .md file in _tutorials/ with YAML front matter following the pattern of the other files, then add a link to it manually in pages/docs_home.html. For a side-by-side tutorial, add a .js file in _tutorials/src, register it in locco.js, run node locco.js, and check in both the JavaScript source and the generated Markdown.

## Sources

- [Issues](https://github.com/jasmine/jasmine.github.io/issues)
- [jasmine/jasmine.github.io on GitHub](https://github.com/jasmine/jasmine.github.io)
- [License: MIT](https://github.com/jasmine/jasmine.github.io/blob/master/LICENSE)
- [Project website](https://jasmine.github.io)
- [README](https://github.com/jasmine/jasmine.github.io/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/jasmine-jasmine-github-io