# keras-io: The Documentation Generator and Example Repository for keras.io

> keras-io is the open-source codebase that generates the keras.io website. It contains the documentation source files, code examples organized by domain, and the autogen.py script that converts Python tutobooks into rendered web pages. Contributing to keras.io means working with this repository.

**keras-team/keras-io** — Keras documentation, hosted live at keras.io

- Repository: https://github.com/keras-team/keras-io
- Stars: 3,008 · Forks: 2,125
- Language: Jupyter Notebook
- License: Apache-2.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/keras-team-keras-io

## What keras-io Is and Who Contributes to It

keras.io is the documentation site for the Keras machine learning framework. keras-io is the repository that generates it. Engineers who use Keras as a library typically have no reason to clone this repository; their entry point is the live site or the Keras Python package. The repository is for contributors who want to add or fix documentation, submit new code examples, or modify the site's templates and scripts.

The README is directed entirely at contributors. It describes the tutobook format, explains which files are auto-generated and must not be edited by hand, and walks through the process of adding a new example from either a Python script or a Jupyter notebook.

The example library covers ten domains, each with its own subdirectory under examples/: audio, generative, graph, keras_recipes, keras_rs, nlp, rl, structured_data, timeseries, and vision. There is also a quickstarts/ directory. Each subdirectory contains the canonical Python source files for that domain's examples.

## The Tutobook Format

A tutobook is a source file that exists in three synchronized forms: a Python script (.py), a Jupyter notebook (.ipynb), and a rendered Markdown page (.md). The Python script is the source of truth. The .ipynb and .md versions are generated by autogen.py and must never be edited by hand.

In the Python script form, text content goes in markdown-formatted comment blocks. The first line of a comment block can carry a special annotation: `shell` causes the block to be executed with a leading `!` when converted to a notebook, and `invisible` prevents the block from being rendered at all.

Every tutobook script starts with a header block containing standard fields:

```python
"""
Title: (title)
Author: (name, may contain markdown links)
Date created: (date in yyyy/mm/dd format)
Last modified: (date in yyyy/mm/dd format)
Description: (one-line text description)
Accelerator: (GPU, TPU, or None)
"""
```

The `add_example` command in autogen.py reads this header to generate the example's index entry. The Accelerator field tells readers whether GPU or TPU access is needed to run the example, which is relevant since most examples are lightweight by design.

## Building the Site Locally

Install the Python dependencies and update Keras, then generate and serve the site:

```
pip install -r requirements.txt
pip install -U keras
cd scripts
python autogen.py make
python autogen.py serve
```

The `make` step executes every example script and generates the corresponding .ipynb and .md files. The `serve` step starts a local HTTP server; the site is accessible at 0.0.0.0:8000.

Alternatively, Docker builds the full site and serves it:

```
docker build -t keras-io . && docker run --rm -p 8000:8000 keras-io
```

The Makefile provides a convenience target that builds the container, starts it, waits ten seconds, checks it is alive, then kills it:

```
make container-test
```

The requirements.txt pins tensorflow to 2.20.0 and includes keras-cv, keras-nlp, keras-hub, keras-tuner, keras-rs, and tf-keras 2.20.0. These cover the full range of Keras libraries whose examples appear on the site. The Docker image is based on python:3.11.

## Contributing Examples: From Notebook to Live Page

To add a new example starting from a Jupyter notebook:

1. Convert the notebook to a tutobook Python script:

```
python tutobooks.py nb2py path_to_your_nb.ipynb ../examples/vision/script_name.py
```

2. Open the generated file, fill in the header fields, and edit for readability. The README warns that the conversion script may produce line breaks that need manual correction.

3. Generate the notebook and Markdown versions:

```
python autogen.py add_example vision/script_name
```

4. Serve the site and navigate to 0.0.0.0:8000/examples to preview.

5. Submit a PR with only the .py file. After review and approval, add the auto-generated files and the PR can be merged.

For examples starting from a Python script: format with black first, add the tutobook header, place the file in the correct examples/ subdirectory, and follow the same add_example and PR process.

Examples are intended to demonstrate workflows at a lightweight scale. The README is explicit: if any cell takes too long to execute during the `add_example` step, the command will error out. Examples that train state-of-the-art models are not accepted; the site shows patterns, not benchmarks.

For typo fixes in existing examples, update the .py, .md, and .ipynb files together in a single PR. For more substantial fixes, submit only the .py file first so the code can be reviewed before regenerating the other formats.

## Which Files Must Never Be Edited by Hand

The autogen.py pipeline generates a large portion of the repository automatically. Editing these generated files by hand means the next time autogen.py runs, the edits are overwritten.

The README lists the off-limits directories explicitly: site/*, sources/*, templates/examples/*, templates/guides/*, and all .md, .ipynb, and .img subdirectories under examples/ and guides/. These are outputs, not inputs.

The editable files are: templates/*.md files that are not under the examples or guides subdirectories, the .py source files under examples/ and guides/, the theme/ directory for site styling, and the scripts/*.py files for the generator itself.

This separation is enforced by convention rather than by the repository tooling. A contributor who edits a generated .md file directly will have their change silently overwritten the next time someone runs `autogen.py make`. Pull requests that include hand-edited generated files are noted in the contributing guide as incorrect.

Documentation generation is performed via the deno_doc project, which is referenced in the README as the right place to open pull requests when documentation rendering itself needs changes rather than the content.

## Documentation Site Architecture and the Alternative

The autogen.py script is a custom static site generator built specifically for the tutobook format. It knows how to execute Python examples, capture their output, and embed it into rendered Markdown pages. This is not a general-purpose documentation tool.

ReadTheDocs is the standard alternative for Python project documentation. It builds documentation from reStructuredText or Markdown source, supports Sphinx for API references, and hosts the result automatically on every push. ReadTheDocs does not have a concept of executable Python examples that run during the build: it documents an API rather than running code and showing the output.

The autogen.py approach is appropriate because keras.io's examples are runnable workflows where the output matters. A documentation generator that cannot execute the code cannot verify that the code still works. The trade-off is a heavier build process: generating the full site runs every example, which requires the full tensorflow, keras, and supporting library stack to be installed.

The call_for_contributions.md file in the repository lists the types of examples the project is currently looking for, which serves as a guide for contributors deciding what to work on.

## Maintenance and License

The last push to the repository was on 2026-09-23. The repository is not archived. The Apache 2.0 license covers the repository contents.

The CODEOWNERS file in .github/ designates specific maintainers for the repository. There are no GitHub releases, since keras-io is a documentation site rather than a versioned software package.

The requirements.txt does not include a top-level keras dependency in the pinned form; instead, the build instructions call `pip install -U keras` to always install the latest Keras version before generating the site. This means the rendered site always reflects the current Keras API rather than a pinned version.

## Conclusion

keras-io is the correct repository to work in when contributing new code examples or fixing documentation bugs on keras.io. The tutobook format is the key constraint: all examples must exist as Python scripts that autogen.py can execute, convert to Markdown, and render to HTML. Anyone who submits a PR for a new example with only a .ipynb or .md file will be asked to provide the .py source instead. The site regenerates from Python source, so examples that take too long to execute are rejected by the preview step. Verify that your example finishes within the execution time limit before submitting.

## FAQ

### What is Keras and why is it used?

Based on the keras.io documentation site this repository generates, Keras is a machine learning framework with code examples covering vision, NLP, generative models, reinforcement learning, time series, and structured data. The examples span both GPU and CPU workloads, and the framework supports multiple backends as indicated by the separate keras-cv, keras-nlp, keras-hub, and keras-rs packages in requirements.txt.

### Is Keras still being used?

The keras-io repository, which generates keras.io, had its last push on 2026-09-23. The requirements.txt is kept current with pinned versions of tensorflow, keras-hub, keras-rs, and related packages, and the build process always installs the latest Keras version before generating the site.

### Is Keras the same as TensorFlow?

They are separate projects. The requirements.txt in this repository lists both tensorflow==2.20.0 and tf-keras==2.20.0 as distinct packages alongside keras-hub, keras-nlp, and keras-cv. Keras is a high-level API that runs on TensorFlow and other backends; they are not the same library.

## Sources

- [Issues](https://github.com/keras-team/keras-io/issues)
- [keras-team/keras-io on GitHub](https://github.com/keras-team/keras-io)
- [License: Apache-2.0](https://github.com/keras-team/keras-io/blob/master/LICENSE)
- [README](https://github.com/keras-team/keras-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/keras-team-keras-io