{"id":13930144,"url":"https://github.com/executablebooks/cookiecutter-jupyter-book","last_synced_at":"2025-12-29T23:34:05.592Z","repository":{"id":45985504,"uuid":"276990146","full_name":"executablebooks/cookiecutter-jupyter-book","owner":"executablebooks","description":"Cookiecutter template for a simple jupyter book","archived":false,"fork":false,"pushed_at":"2023-11-29T23:08:39.000Z","size":2894,"stargazers_count":140,"open_issues_count":7,"forks_count":53,"subscribers_count":11,"default_branch":"main","last_synced_at":"2024-09-05T02:40:08.538Z","etag":null,"topics":["cookiecutter-template","jupyter-book","python","workflow"],"latest_commit_sha":null,"homepage":"https://executablebooks.github.io/cookiecutter-jupyter-book/","language":"TeX","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/executablebooks.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-07-03T21:27:47.000Z","updated_at":"2024-08-26T18:04:41.000Z","dependencies_parsed_at":"2023-02-17T00:10:25.841Z","dependency_job_id":"ad3e6a9b-9c44-405c-b504-0ac3c61afbea","html_url":"https://github.com/executablebooks/cookiecutter-jupyter-book","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/executablebooks%2Fcookiecutter-jupyter-book","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/executablebooks%2Fcookiecutter-jupyter-book/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/executablebooks%2Fcookiecutter-jupyter-book/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/executablebooks%2Fcookiecutter-jupyter-book/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/executablebooks","download_url":"https://codeload.github.com/executablebooks/cookiecutter-jupyter-book/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226607597,"owners_count":17658482,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cookiecutter-template","jupyter-book","python","workflow"],"created_at":"2024-08-07T18:04:50.012Z","updated_at":"2025-12-29T23:34:05.556Z","avatar_url":"https://github.com/executablebooks.png","language":"TeX","funding_links":[],"categories":["python","Usage"],"sub_categories":["Hosting the book"],"readme":"# Cookiecutter Jupyter Book\n\n![tests](https://github.com/executablebooks/cookiecutter-jupyter-book/workflows/tests/badge.svg)\n![deploy](https://github.com/executablebooks/cookiecutter-jupyter-book/workflows/deploy/badge.svg)\n[![release](https://img.shields.io/github/release/executablebooks/cookiecutter-jupyter-book.svg)](https://github.com/executablebooks/cookiecutter-jupyter-book/releases)\n[![python](https://img.shields.io/badge/python-3.8%2C%203.9%2C%203.10-blue)]()\n[![os](https://img.shields.io/badge/OS-Ubuntu%2C%20Mac%2C%20Windows-yellow)]()\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"{{cookiecutter.book_slug}}/{{cookiecutter.book_slug}}/logo.png\" width=\"400\"\u003e\n\u003c/p\u003e\n\nA cookiecutter template for creating a simple [Jupyter Book](https://jupyterbook.org/intro.html). See the rendered version of this cookiecutter template [here](https://executablebooks.github.io/cookiecutter-jupyter-book/).\n\n## Template\n\nAn example template created by this cookiecutter is shown below:\n\n```\nmy_book\n├── .github\n│   └── workflows\n│       └── deploy.yml\n├── CONDUCT.md\n├── CONTRIBUTING.md\n├── LICENSE\n├── my_book\n│   ├── _config.yml\n│   ├── _toc.yml\n│   ├── content.md\n│   ├── intro.md\n│   ├── logo.png\n│   ├── markdown.md\n│   ├── markdown-notebooks.md\n│   ├── notebooks.ipynb\n│   └── references.bib\n├── README.md\n└── requirements.txt\n```\n\n## Usage\n\n1. Install [Cookiecutter](https://github.com/cookiecutter/cookiecutter/tree/1.7.2) if you haven't installed it yet:\n\n```bash\n$ pip install -U cookiecutter jupyter-book\n```\n\n2. Use `cookiecutter-jupyter-book` to generate a Jupyter Book template and fill out the requested information (default templating values are shown in square brackets `[]` and will be used if no other information is entered):\n\n```bash\n$ cookiecutter git@github.com:executablebooks/cookiecutter-jupyter-book.git\n\nauthor_name [Captain Jupyter]: Tomas Beuzen\ngithub_username [tomasbeuzen]:\nbook_name [My Book]:\nbook_slug [my_book]:\nbook_short_description [This cookiecutter creates a simple boilerplate for a Jupyter Book.]: My first Jupyter Book!\nversion ['0.1.0']:\nSelect open_source_license:\n1 - MIT license\n2 - BSD license\n3 - Apache Software License 2.0\n4 - CC BY 4.0\n5 - CC BY-SA 4.0\n6 - None\nChoose from 1, 2, 3, 4, 5, 6 [1]:\nSelect include_ci:\n1 - github\n2 - gitlab\n3 - no\nChoose from 1, 2, 3 [1]:\n```\n\n3. Install the Jupyter Book package requirements from the `requirements.txt` file (it is recommended to do this in a virtual environment, e.g., using [conda](https://docs.conda.io/en/latest/)):\n\n```bash\n# Optional steps to create and activate virtual environment\n$ conda create --name mybook python=3.8 -y\n$ conda activate mybook\n```\n\n```bash\n$ cd my_book\n$ pip install -r requirements.txt\n```\n\n4. Build the HTML render of your Jupyter Book:\n\n```bash\n$ jupyter-book build my_book/\n```\n\n5. View your rendered book in `my_book/_build/html/index.html`.\n\n6. Make edits to your book by adding more content, updating the table of contents in `my_book/_toc.yml`, and and/or by editing the configuration file `my_book/_config.yml`. See the [Jupyter Book documentation](https://jupyterbook.org/intro.html) for more information on customizing your book.\n\n7. `cookiecutter-jupyter-book` optionally comes with CI workflow files to help easily deploy your book online. A CI workflow file would have been included in your directory structure if you chose `1 - github` or `2 - gitlab` for `Select include_ci_files:` in Step 2 above. For example, if you chose `1 - github`, when ready to deploy your book online:\n   1. Make sure your book builds locally as expected (`jupyter-book build my_book/`) and that you have updated the `requirements.txt` file to include any additional packages required to build your book;\n   2. Create a new public [GitHub repository](https://github.com/new) to host your book;\n   3. Push your local book (including the `.github` hidden directory) to your GitHub repository. There are many ways to do this, for example:\n\n      ```bash\n      $ git init\n      $ git add .\n      $ git commit -m \"first commit\"\n      $ git remote add origin git@github.com:\u003cuser\u003e/\u003crepository-name\u003e.git\n      $ git push -u origin main\n      ```\n\n   4. The GitHub Actions workflow provided with the cookiecutter (`my_book/.github/workflows/deploy.yml`) will automatically deploy your book to the `gh-pages` branch of your repository once pushed. It is typically available after a few minutes at `https://\u003cuser\u003e.github.io/\u003cmyonlinebook\u003e/`. You may need to go to the `Settings` tab of your repository and under the **GitHub Pages** heading, choose the `gh-pages branch` from the **Source** drop-down list. For alternative methods of deploying your book online, see the See the [Jupyter Book documentation](https://jupyterbook.org/intro.html).\n\n   \u003e Note: by default, the GitHub Actions workflow file included with this cookiecutter builds the book with Ubuntu and Python 3.8. You can modify the OS/Python version for the build in the `.github/workflows/deploy.yml` file on lines 15 and 16 respectively.\n\n   \u003e Read more about GitHub Pages and Jupyter Book [here](https://jupyterbook.org/publish/gh-pages.html#automatically-host-your-book-with-github-actions), or using GitLab Pages [here](https://docs.gitlab.com/ee/user/project/pages/getting_started/pages_from_scratch.html).\n\n## Contributing\n\nWe welcome and recognize all contributions. If you'd like to contribute to the project by providing feedback, identifying a bug or working on a new feature, check out the [contributing guide](CONTRIBUTING.md) to get started.\n\nYou can see a list of current contributors in the [contributors tab](https://github.com/executablebooks/cookiecutter-jupyter-book/graphs/contributors).\n\n## Acknowledgements\n\nThis template was inspired and made possible by the [Cookiecutter project](https://github.com/cookiecutter/cookiecutter) and the [Jupyter Book project](https://github.com/executablebooks/jupyter-book).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexecutablebooks%2Fcookiecutter-jupyter-book","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexecutablebooks%2Fcookiecutter-jupyter-book","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexecutablebooks%2Fcookiecutter-jupyter-book/lists"}