{"id":13954294,"url":"https://github.com/IIIF-Commons/biiif","last_synced_at":"2025-07-20T16:32:16.997Z","repository":{"id":38963469,"uuid":"111013903","full_name":"IIIF-Commons/biiif","owner":"IIIF-Commons","description":"Organise your files according to a simple naming convention to generate IIIF Presentation API json using nodejs (Dat and IPFS compatible)","archived":false,"fork":false,"pushed_at":"2023-10-07T23:19:03.000Z","size":1082,"stargazers_count":86,"open_issues_count":21,"forks_count":11,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-04-13T21:06:34.866Z","etag":null,"topics":["iiif","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IIIF-Commons.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-11-16T19:36:53.000Z","updated_at":"2024-02-23T00:04:28.000Z","dependencies_parsed_at":"2022-09-19T15:11:52.640Z","dependency_job_id":"77ba1cdf-c171-4874-92e8-ad4ea009c215","html_url":"https://github.com/IIIF-Commons/biiif","commit_stats":null,"previous_names":["edsilv/biiif"],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IIIF-Commons%2Fbiiif","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IIIF-Commons%2Fbiiif/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IIIF-Commons%2Fbiiif/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IIIF-Commons%2Fbiiif/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IIIF-Commons","download_url":"https://codeload.github.com/IIIF-Commons/biiif/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226818479,"owners_count":17686979,"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":["iiif","nodejs"],"created_at":"2024-08-08T08:00:39.239Z","updated_at":"2025-07-20T16:32:16.990Z","avatar_url":"https://github.com/IIIF-Commons.png","language":"JavaScript","funding_links":[],"categories":["Presentation Manifest Tools"],"sub_categories":["Image viewers (Image API only)"],"readme":"# biiif (build iiif) 👷✨📃\n\n[![Node version](https://img.shields.io/node/v/biiif.svg?style=flat)](http://nodejs.org/download/)\n\n\u003c!-- ![IIIF Presentation API 3 compliant](https://img.shields.io/badge/iiif--presentation--api-%3E=3-blue.png) --\u003e\n\n```bash\nnpm i biiif --save\n```\n\n```bash\nconst { build } = require('biiif');\nbuild('myfolder', 'http://example.com/myfolder');\n```\n\nOrganise your files according to a simple [naming convention](https://github.com/edsilv/biiif#examples) to generate [IIIF](http://iiif.io) content/data using 100% node.js! [IPFS](https://github.com/ipfs) compatible.\n\nUse [biiif-cli](https://github.com/edsilv/biiif-cli) to run from a terminal.\n\nNote: This uses the [IIIF Presentation API v3](http://prezi3.iiif.io/api/presentation/3.0/), and is compatible with the [Universal Viewer](http://universalviewer.io) v3.\n\nGithub template repo for hosting IIIF on Netlify and Vercel: https://github.com/iiif-commons/biiif-template\n\nBuilding static sites with biiif workshop: https://github.com/edsilv/biiif-workshop\n\n## Parameters\n\n| Parameter     | Type   | Description                                                                                                                                     |\n| :------------ | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------- |\n| `folder`      | string | The source folder of your IIIF collection/manifest on disk                                                                                      |\n| `url`         | string | The Url to use as the root for all generated manifest, asset identifiers                                                                        |\n| `virtualName` | string | Overrides the source folder name when generating identifiers e.g. a dat archive id you need to appear in Urls instead of the source folder name |\n\n## Conventions\n\nA collection is a folder with sub-folders whose names _do not_ start with an underscore.\n\nA manifest is a folder with sub-folders whose names _do_ start with an underscore.\n\nA collection's sub-folders (no underscore) are treated as further nested collections.\n\nA manifest's sub-folders (with underscore) are treated as canvases to add to the manifest.\n\nFiles within 'canvas folders' (.jpg, .pdf, .mp4, .obj) are annotated onto the canvas with a `painting` motivation.\n\n## Annotations\n\nIIIF Presentation 3.0 uses the [Web Annotation Data Model](https://www.w3.org/TR/annotation-model/) to annotate canvases.\n\nBy default, biiif will annotate any files it finds in a canvas directory (except `info.yml` and `thumb.jpg`) onto the canvas with a `painting` motivation.\n\nThis is handy as a quick way to generate simple manifests. However, what if you want to annotate some text onto a canvas with a `commenting` motivation?\n\nOr what happens when you have obj or gltf files that require image textures to be located in the same directory? You don't want these files to be annotated onto the canvas too!\n\nThis is where custom annotations come in. Just create a file `my-annotation.yml` in the canvas directory and set the desired properties in that.\n\nFor example, here is `my-comment.yml`:\n\n```yml\nmotivation: commenting\nvalue: This is my comment on the image\n```\n\nHere we've excluded the `type` (`TextualBody` is assumed), and `format` (`text/plain` is assumed).\n\nWhat about the gltf example? Here's how `my-3d-object.yml` could look:\n\n```yml\nvalue: assets/myobject.gltf\n```\n\nHere we've excluded the `motivation` (`painting` is assumed), `type` (`Model` is assumed), and `format` (`model/gltf+json` is assumed).\n\nbiiif knows that because it's a gltf file, it's likely to have all of the above values. You just need to include a `value` property pointing to where you've put the gltf file itself. In this case, an `assets` folder within the canvas directory. The associated image textures can live in the `assets` folder too, they won't get annotated unless you specifically ask for them to be.\n\n## Image Tile Services\n\nbiiif will automatically generate IIIF image tiles for any image it finds and put them in a `+tiles` directory, along with an associated `info.json`. The `+` is prepended to any directories generated by biiif and means it ignores them when generating manifests.\nThe image service is added to the generated annotation for each image in your IIIF manifest.\n\n## Metadata\n\nMetadata is not mandatory, but can be included as an `info.yml` file within a collection, manifest, or canvas folder. e.g.\n\n```yml\nlabel: The Lord of the Rings\ndescription: The Lord of the Rings Trilogy\nattribution: J. R. R. Tolkien\nmetadata:\n  License: Copyright Tolkien Estate\n  Author: J. R. R. Tolkien\n  Published Date: 29 July 1954\n```\n\nHere's an example of an `info.yml` supplying descriptive + rights properties and metadata for a gold-broach image manifest:\n\nhttps://github.com/nomadproject/objects/blob/gh-pages/collection/gold-broach/info.yml\n\nThis manifest contains a single canvas folder `_gold-broach` with an image to be painted onto the canvas. If there were many canvases in this manifest it might make sense to add an `info.yml` to each subfolder with extra image-specific metadata.\n\nWithin the `info.yml` you can set the `label`, `description`, and `attribution` [descriptive and rights properties](https://iiif.io/api/presentation/3.0/#appendices) at the top-level. IIIF Presentation 3 (in beta) has renamed `description` to `summary`, and `attribution` to `requiredStatement` but these will still work in IIIF viewers.\n\nUnder these you can add a `metadata` section that is essentially a list of key value pairs containing any info you like (there is deliberately no specification for this as the IIIF spec writers feel it falls outside of their remit).\n\n## Thumbnails\n\nTo add a thumbnail to your collection, manifest, or canvas simply include a file named `thumb.jpg` (any image file extension will work) in the directory.\n\nIf no thumb image is found in a canvas directory, biiif checks to see if an image is being annotated onto the canvas with a painting motivation. If so, a thumb is generated (100 x 100px) from that.\n\n## Linked Manifests\n\nOften it's necessary to include IIIF manifests in your collection from elsewhere. To do this, include a `manifests.yml` file in your collection folder e.g.\n\n```yml\nmanifests:\n  - id: http://test.com/collection/linkedmanifest1/index.json\n    label: Linked Manifest 1\n    thumbnail: http://test.com/collection/linkedmanifest1/thumb.jpg\n  - id: http://test.com/collection/linkedmanifest2/index.json\n    label: Linked Manifest 2\n  - id: http://test.com/collection/linkedmanifest3/index.json\n```\n\nIf you leave the `label` property blank, it will default to the name of the last folder in the `id` URL.\n\nIncluding a `manifests.yml` file in a folder without any sub-folders forces it to behave like a collection.\n\n## Examples\n\n\u003c!--MozFest zine workshop published on glitch: https://glitch.com/~edsilv-mozfest-zine--\u003e\n\nA repo of test manifests: https://github.com/edsilv/biiif-test-manifests\n\nCollection for the [Nomad Project](https://nomad-project.co.uk): https://github.com/nomadproject/objects\n\nIIIF 3D manifests: https://github.com/edsilv/iiif-3d-manifests\n\n...\n\nHere is an example of how to organise your files/folders for biiif.\n\nThis example only has a single root collection, but biiif will happily build collections to any nested depth.\n\nbiiif will accept a manifest folder too, generating a single manifest `index.json`.\n\n```yml\nlord-of-the-rings                  // collection\n├── info.yml                       // collection metadata\n├── thumb.jpg                      // collection thumbnail\n├── 0-the-fellowship-of-the-ring   // manifest\n|   ├── _page-1                    // canvas\n|   |   ├── page-1.jpg             // content annotation\n|   |   └── info.yml               // canvas metadata\n|   ├── _page-2                    // canvas\n|   |   ├── page-2.jpg             // content annotation\n|   |   └── info.yml               // canvas metadata\n|   ├── _page-n                    // canvas\n|   |   ├── page-n.jpg             // content annotation\n|   |   └── info.yml               // canvas metadata\n|   ├── info.yml                   // manifest metadata\n|   └── thumb.jpg                  // manifest thumbnail\n├── 1-the-two-towers               // manifest\n|   ├── _page-1                    // canvas\n|   ├── _page-2                    // canvas\n|   ├── _page-n                    // canvas\n|   ├── info.yml                   // manifest metadata\n|   └── thumb.jpg                  // manifest thumbnail\n└── 2-the-return-of-the-king       // manifest\n    ├── _page-1                    // canvas\n    ├── _page-2                    // canvas\n    ├── _page-n                    // canvas\n    ├── info.yml                   // manifest metadata\n    └── thumb.jpg                  // manifest thumbnail\n```\n\n## Tips\n\nIf you need to include a folder in your project but don't want biiif to treat it as a manifest, add a `!` to the start of its name, e.g. `!ignorethisfolder`.\n\nWatch out for \":\" in metadata descriptions, these will throw an error when parsing the YML.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIIIF-Commons%2Fbiiif","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FIIIF-Commons%2Fbiiif","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIIIF-Commons%2Fbiiif/lists"}