{"id":29255268,"url":"https://github.com/astropy-learn/nbcollection","last_synced_at":"2025-07-04T03:04:29.051Z","repository":{"id":44642263,"uuid":"228293488","full_name":"astropy-learn/nbcollection","owner":"astropy-learn","description":"Execute and convert collections of Jupyter notebooks to static HTML","archived":true,"fork":false,"pushed_at":"2025-06-12T08:39:51.000Z","size":448,"stargazers_count":12,"open_issues_count":5,"forks_count":8,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-06-28T21:08:14.549Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Jupyter Notebook","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/astropy-learn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"numfocus","custom":"https://numfocus.org/donate-to-astropy"}},"created_at":"2019-12-16T03:17:26.000Z","updated_at":"2025-06-12T08:40:13.000Z","dependencies_parsed_at":"2022-09-05T12:51:29.471Z","dependency_job_id":"5d4438ec-38d9-407e-987d-356a2397aeaa","html_url":"https://github.com/astropy-learn/nbcollection","commit_stats":{"total_commits":285,"total_committers":10,"mean_commits":28.5,"dds":"0.43157894736842106","last_synced_commit":"608a1f8271d5399d6f4cd55b4829a02d9d50a40b"},"previous_names":["adrn/nbcollection","adrn/nbstatic","astropy-learn/nbcollection"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/astropy-learn/nbcollection","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astropy-learn%2Fnbcollection","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astropy-learn%2Fnbcollection/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astropy-learn%2Fnbcollection/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astropy-learn%2Fnbcollection/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/astropy-learn","download_url":"https://codeload.github.com/astropy-learn/nbcollection/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astropy-learn%2Fnbcollection/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263437326,"owners_count":23466363,"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":[],"created_at":"2025-07-04T03:01:33.153Z","updated_at":"2025-07-04T03:04:29.029Z","avatar_url":"https://github.com/astropy-learn.png","language":"Jupyter Notebook","funding_links":["https://github.com/sponsors/numfocus","https://numfocus.org/donate-to-astropy"],"categories":[],"sub_categories":[],"readme":"**Archive note: The functionality this repository provided is now integrated into the workflow process run over individual tutorial repositories. See the `build.yml` workflow in a given tutorial repository and the `action--` repositories in this organization.**\n\n# nbcollection\n\nTools for building collections of Jupyter notebooks into web pages for public\nconsumption.\n\nThis project serves as a thin wrapper around `nbconvert` to enable converting\nand executing directories or directory structures full of Jupyter notebooks to\nstatic HTML pages.\n\n## License\n\n`nbcollection` is free software made available under the MIT License. For details\nsee the LICENSE file.\n\n--------\n\n## Example usage\n\n### Default behavior:\n\n#### Converting a directory structure of specific notebook files\n\nImagine we have a directory containing Jupyter notebook files and some other\nsub-directories that also contain notebook files, such as:\n\n    my_notebooks\n    ├── notebook1.ipynb\n    └── sub_path1\n        ├── notebook2.ipynb\n        └── notebook3.ipynb\n\nFrom the top level, we could use `nbcollection` to execute and convert all of these\nnotebook files to HTML by running:\n\n    nbcollection convert my_notebooks\n\nWith no options specified, this will create a directory within the specified\npath, `my_notebooks/_build`, to store the executed notebooks and the converted\nHTML pages:\n\n    my_notebooks\n    └── _build\n        ├── notebook1.ipynb\n        ├── notebook1.html\n        └── sub_path1\n            ├── notebook2.ipynb\n            ├── notebook3.ipynb\n            ├── notebook2.html\n            └── notebook3.html\n\nIf you are only interested in executing the notebooks, you can instead use the\n`execute` command:\n\n    nbcollection execute my_notebooks\n\nwhich still creates a new `_build` path but now only contains the executed\nnotebook files:\n\n    my_notebooks\n    └── _build\n        ├── notebook1.ipynb\n        └── sub_path1\n            ├── notebook2.ipynb\n            └── notebook3.ipynb\n\n\n#### Converting a list of specific notebook files\n\nInstead of running on a full directory, it is also possible to convert or\nexecute single notebook files (but you should probably use `jupyter nbconvert`\ndirectly), or lists of notebook files. For example, to convert a set of specific\nnotebook files within the above example directory layout:\n\n    nbcollection convert my_notebooks/notebook1.ipynb my_notebooks/sub_path1/notebook2.ipynb\n\nBecause these files could in principle be in two completely separate paths, the\nbuild products here will instead be written to the current working directory by\ndefault (but see the command option `--build-path` below to customize). So, the\nabove command would result in:\n\n    _build\n    ├── notebook1.ipynb\n    └── sub_path1\n        └── notebook2.ipynb\n\n\n### Command options:\n\nSeveral options are available to modify the default behavior of the `nbcollection`\ncommands.\n\n#### Customizing the build path\n\nAs outlined above, the default locations for storing the executed notebooks or\nconverted HTML pages is either in a parallel directory structure contained\nwithin a `_build` directory created at the top-level of the specified path, or\nin a `_build` path in the current working directory (if a list of notebook files\nare specified). However, the build path can be overridden and specified\nexplicitly by specifying the `--build-path` command line flag. For example, with\nthe notebook directory structure illustrated in the above examples, we could\ninstead specify the build path with:\n\n    nbcollection convert my_notebooks --build-path=/new/path/my_build\n\nWith this option specified, the executed notebook files and converted HTML\nnotebooks would be placed under `/new/path/my_build` instead.\n\n\n#### Flattening the built file structure\n\nIf your notebook files are spread throughout a nested directory structure, you\nmay want to place all of the converted notebook files in a single path rather\nthan reproduce the relative path structure of your content. To enable this, use\nthe `--flatten` boolean flag. For example, if your content has the following\npath structure:\n\n    my_notebooks\n    ├── notebook1.ipynb\n    └── sub_path1\n        ├── notebook2.ipynb\n        └── notebook3.ipynb\n\nYou can convert all of the notebooks to a single build path with:\n\n    nbcollection convert my_notebooks --flatten\n\nThis will result in:\n\n    my_notebooks\n    └── _build\n        ├── notebook1.ipynb\n        ├── notebook2.ipynb\n        ├── notebook3.ipynb\n        ├── notebook1.html\n        ├── notebook2.html\n        └── notebook3.html\n\nThis command also works in conjunction with `--build-path` if you want to, e.g.,\nconvert a list of individual notebook files and have the build products end up\nin the same root path.\n\n\n#### Specifying a custom template file\n\n`nbconvert` allows specifying custom `jinja2` [template\nfiles](https://nbconvert.readthedocs.io/en/latest/customizing.html) for\nexporting notebook files to HTML. We support this through the `--template`\ncommand-line flag, which allows specifying a path to a `jinja2` template file.\nFor example:\n\n    nbcollection convert my_notebooks --template-file=templates/custom.tpl\n\n#### Extracting figures and other preprocessors\n\nYou can enable additional\n[preprocessors](https://nbconvert.readthedocs.io/en/latest/api/preprocessors.html#specialized-preprocessors)\nfor the HTML exporter by passing one or more preprocessor names to the\n`--preprocessors` option. A useful preprocessor is `ExtractOutputPreprocessor`,\nwhich extracts figures from the HTML into separate files for better page loading\nperformance:\n\n    nbcollection convert my_notebooks --preprocessors=nbconvert.preprocessors.ExtractOutputPreprocessor\n\n#### Only execute the notebooks\n\nThough the primary utility of `nbcollection` is to enable converting a collection of\nnotebook files to static HTML pages, you can also use the `nbcollection execute`\ncommand to instead only execute a collection of notebooks. This command is used\nthe same way as `nbcollection convert`, but also enable executing the notebook files\nin place as a way to test the notebooks. To execute a collection of notebooks\nin-place (i.e., this will not create a `_build` path with the executed\nnotebooks):\n\n    nbcollection execute my_notebooks --inplace\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastropy-learn%2Fnbcollection","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fastropy-learn%2Fnbcollection","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastropy-learn%2Fnbcollection/lists"}