{"id":13631181,"url":"https://github.com/ipld/ipld","last_synced_at":"2025-05-14T05:08:00.732Z","repository":{"id":37734859,"uuid":"71267812","full_name":"ipld/ipld","owner":"ipld","description":"InterPlanetary Linked Data","archived":false,"fork":false,"pushed_at":"2025-05-01T15:39:16.000Z","size":27758,"stargazers_count":1298,"open_issues_count":81,"forks_count":167,"subscribers_count":83,"default_branch":"master","last_synced_at":"2025-05-12T05:03:38.968Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://ipld.io","language":"Nunjucks","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ipld.png","metadata":{"files":{"readme":"README-writing-guide.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}},"created_at":"2016-10-18T16:21:12.000Z","updated_at":"2025-05-12T04:11:32.000Z","dependencies_parsed_at":"2023-09-27T06:01:53.558Z","dependency_job_id":"27a0ac23-6779-44e9-b1a5-4cfebba89326","html_url":"https://github.com/ipld/ipld","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipld%2Fipld","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipld%2Fipld/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipld%2Fipld/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipld%2Fipld/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ipld","download_url":"https://codeload.github.com/ipld/ipld/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254076697,"owners_count":22010611,"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":"2024-08-01T22:02:14.161Z","updated_at":"2025-05-14T05:08:00.693Z","avatar_url":"https://github.com/ipld.png","language":"Nunjucks","funding_links":[],"categories":["Nunjucks"],"sub_categories":[],"readme":"Writing Guide\n=============\n\nThis document is a brief writing guide for contributing to the IPLD project's docs, specs, and website.\nPlease give it a quick skim when considering proposing new content.\n\n\nWhich Major Group?\n------------------\n\nThis repo has a couple major directories at the top level:\n\n- **docs**\n- **specs**\n- **libraries**\n- **tools**\n- **design**\n- **notebook**\n\nThese have slightly different audiences, and slightly different editing policies:\n\n- **docs** -- end-user documentation goes here; these documents generally emphasize readability over detail.\n  Things in the docs folders should link to the specs folders when more detail is needed.\n  The docs folders are rendered to the website.\n- **specs** -- high-detail specifications go here.  These are more for library and tool implementers than end-users of IPLD systems.\n  The writing style should be drier (it need not be convincing or friendly; that's for the docs folder).\n  The specs folders are rendered to the website.\n- **libraries** -- these pages gather *brief* references to IPLD libraries.  They should mostly refer to other repositories; it's just a discovery index.\n  Some of these pages will refer to libraries not directly maintained by the IPLD core team!\n  The libraries index pages are rendered to the website.\n- **tools** -- these pages gather *brief references to IPLD tools.  They should mostly refer to other repositories; it's just a discovery index.\n  Some of these pages will refer to tools not directly maintained by the IPLD core team!\n  The tools index pages are rendered to the website.\n- **design** -- these pages contain some recommendations for building IPLD libraries and data structures.\n  They're general notes about how things \"should\" be done.\n  Some of these notes also cover the foundational reasoning we used in making key choices in IPLD's core definitions.\n- **notebook** -- this folder is for notes like design documents, architecture decision records, and similar point-in-time content.\n  Sometimes the IPLD core team writes documents here, but it's equally encouraged to write \"lab notebook\"-style documents in other mediums and link to them from here.\n  Things here are non-definitive references.\n  Note that the design notebook pages are *not* rendered to the website.\n  We consider them more like draft and historical interest content, and so give them correspondingly much less spotlight.\n\nIf writing new content, consider which group to aim for.\n\n- If you're working on a third-party IPLD tool or library, we're happy to list it under the tools and libraries pages!\n- If you'd like to log a link to an experience report, writing somewhere else and then making a PR to the notebook pages with a link might be the right thing to do.\n- For any major content: first drafts should very likely go through some sort of notebook process.\n  (Please don't make PRs to the specs folders directly; anything bigger than a typo fix is very unlikely to be able to land directly.  Use the notebook instead!)\n- If it's for end-user information, a PR to docs might be appropriate.\n- If you're thinking of a specs proposal: goto two bullet points above :)\n\n\nFile Organization\n-----------------\n\n### READMEs are for github\n\nWe use `README.md` files in some directories to provide information about editing this area.\n\nWe don't render `README.md` files to the website,\nso they're a reasonable place to put editing guideline information,\nor other content that's appropriate to a git/github audience but not relevant folks reading the website.\n\n\n### how files render to web\n\nFiles named `index.*` (in particular, `index.md`) are rendered to the website.\nSo, content in the path `foo/bar/index.md` will render on the website at `foo/bar/`.\n\nOther files also render to the website, but have their filename turn into a bare directory (because extensions on URLs is so not-this-year):\nso, content in the path `foo/bar.md` would also render on the website at `foo/bar/`.\n\nTherefore, if you have a \"large\" page, with lots of content and images related to it, consider putting it in its own directory\nand putting most of the content in an `index.md` file.\n\n`index.md` that have other pages underneath them (either sibling `*.md` files, or whole directories of content)\nshould probably aim to have minimal amounts of content themselves, and just provide a quick overview and table of links to the child content.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipld%2Fipld","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fipld%2Fipld","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipld%2Fipld/lists"}