{"id":18809693,"url":"https://github.com/opencontainers/specs.opencontainers.org","last_synced_at":"2025-06-27T22:37:34.555Z","repository":{"id":141667613,"uuid":"405144490","full_name":"opencontainers/specs.opencontainers.org","owner":"opencontainers","description":"OCI Specs Documentation","archived":false,"fork":false,"pushed_at":"2024-04-02T19:55:46.000Z","size":1601,"stargazers_count":7,"open_issues_count":3,"forks_count":5,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-05-22T02:41:00.322Z","etag":null,"topics":["oci"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/opencontainers.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2021-09-10T16:26:45.000Z","updated_at":"2024-12-05T02:11:53.000Z","dependencies_parsed_at":"2025-02-19T22:38:31.007Z","dependency_job_id":null,"html_url":"https://github.com/opencontainers/specs.opencontainers.org","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/opencontainers/specs.opencontainers.org","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencontainers%2Fspecs.opencontainers.org","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencontainers%2Fspecs.opencontainers.org/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencontainers%2Fspecs.opencontainers.org/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencontainers%2Fspecs.opencontainers.org/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opencontainers","download_url":"https://codeload.github.com/opencontainers/specs.opencontainers.org/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opencontainers%2Fspecs.opencontainers.org/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262346025,"owners_count":23296815,"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":["oci"],"created_at":"2024-11-07T23:17:18.583Z","updated_at":"2025-06-27T22:37:34.480Z","avatar_url":"https://github.com/opencontainers.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Opencontainers Specs\n\n**⭐️ Welcome to the Opencontainers Specs Documentation! ⭐️**\n\n![assets/img/runtime-spec.png](assets/img/runtime-spec.png)\n\nThis is built with [vsoch/rfc-jekyll](https://github.com/vsoch/rfc-jekyll),\nand provides the following features:\n\n1. You can combine many different resources across multiple repos to look like one holistic documentation base\n2. Content is retrieved dynamically directly from the specs and you don't need to rebuild.\n3. Adding new pages comes down to adding metadata for the pages you want.\n\n[View the specs!](https://specs.opencontainers.org/)\n\n## Usage\n\n### 1. Get the code\n\nYou can clone the repository right to where you want to host the docs:\n\n```bash\ngit clone https://github.com/ ./docs\ncd docs\n```\n\n### 2. Customize\n\n#### Jekyll Config\n\nTo edit configuration values, customize the [_config.yml](https://github.com/opencontainers/specs.opencontainers.org/blob/main/_config.yml).\nThis includes details like the site title and basename.\n\n#### How are documents defined?\n\nThe [pages](pages) folder contains subfolders that are each examples of specs.\nFor example, [pages/images-spec](pages/image-spec) includes multiple markdown\nfiles that are rendered from [opencontainers/image-spec](https://github.com/opencontainers/image-spec).\n\n##### 1. Document Metadata\n\nThe [_data/specs.yaml](_data/specs.yaml) file defines shared attributes for an\nentire spec folder. For example, let's take a look at this data file's definition\nfor `image-spec`:\n\n```yaml\n# This file holds shared metadata for a directory of specs\nimage-spec:\n  name: Image Spec\n  group: Open Containers Initiative (OCI)\n  github_repo: opencontainers/image-spec\n  default_version: v1.0.1\n  versions:\n    - v1.0.1\n\n  # Courtesy list of pages relative to site root to link\n  pages:\n   - image-spec/\n   - image-spec/annotations/\n   - image-spec/config/\n   - image-spec/considerations/\n   - image-spec/conversions/\n   - image-spec/descriptor/\n   - image-spec/image-index/\n   - image-spec/image-layout/\n   - image-spec/layer/\n   - image-spec/manifest/\n   - image-spec/media-types/\n```\n\nThe various urls are used to define relative paths in the repository. The list\nof pages (optional) will render a left side navigation to give the reader\ncontext of all the documents included for a spec. Importantly, the key `image-spec`\nat the top is used to lookup this metadata. Finally, the list of versions should\ncorrespond to releases. If a release isn't given in the browser as a variable,\nthen we fall back to the `default_version` variable.\n\n##### 2. Document Index Page\n\nNow we can look at an `index.md`\nin [pages/image-spec/index.md](pages/image-spec/index.md) that is considered the\nroot of a spec:\n\n```yaml\n---\nlayout: page\ntitle: The OpenContainers Image Spec\nid: IMAGE-SPEC\npermalink: /image-spec/\nspec: spec.md\n# data key from _data/specs.yaml\nkey: image-spec\n---\n```\n\nNote the key `image-spec` will be used for the lookup. We primarily need to know\nthe name of the markdown file that will render into the page (`spec.md`) and then\ncustom, page-specific attributes like the permalink and title.\n\n##### 3. Document Additional Pages\n\nNow let's say that we have a second markdown file linked from this spec called `manifest.md`.\nThe template will find these links and render them into relative urls, so we also add\npages for them. In the case of `manifest.md` the metadata would be almost the same, \nbut we'd update the name of the spec from `spec.md` to `manifest.md` and **important**\nwe would have the permalink be a relative path to it's parent, image spec:\n\n```yaml\n---\nlayout: page\ntitle: The OpenContainers Image Manifest Spec\nid: IMAGE-SPEC-MANIFEST\npermalink: /image-spec/manifest/\nspec: manifest.md\nparent: image-spec\nkey: image-spec\n---\n```\n\nYou'll notice a new field - **parent**. This is here so that we can correctly\nformat links in the correct namespace. The reason for this metadata is because we render the pages doing the following:\n\n1. Retrieve raw markdown text from the `raw_url` + `/` + `spec`\n2. For each image tag we find, if the url is relative, we add the `raw_url` so the image renders.\n3. For each link that we find with a markdown file (that is not linked to another repository) we remove the `.md` extension and turn it into a path. This means that the final url looks like a relative path of the filename. (E.g., manifest.md linked relatively turns into `manifest/` linked from the current page, or `/image-spec/manifest/`.\n\n\n#### How do I add a new document?\n\nThus, to add a new document you should:\n\n1. Add an entry to [_data/specs.yaml](_data/specs.yaml)\n2. Add a new subfolder in [pages](pages)\n3. Create an index.md within using the metadata examples above. The permalink of the index should reference the root.\n4. Markdown files linked from that page should be added with a permalink relative to the index, and a parent of the root.\n\nThis means that when adding a new spec, you will need to do work once to go through these steps,\nbut then you never need to update it again. The spec will load dynamically whenever the site is needed,\nand there is no rebuild necessary. \n\n#### How do I get help?\n\nIf you want to add a new OCI document and are having trouble, please [open an issue](https://github.com/opencontainers/specs.opencontainers.org/issues)\nto request it to be added.\n\n### 3. Serve\n\nDepending on how you installed jekyll:\n\n```bash\njekyll serve\n# or\nbundle exec jekyll serve\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencontainers%2Fspecs.opencontainers.org","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopencontainers%2Fspecs.opencontainers.org","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencontainers%2Fspecs.opencontainers.org/lists"}