{"id":19899503,"url":"https://github.com/brightercommand/rewind","last_synced_at":"2025-03-01T06:44:27.276Z","repository":{"id":182896432,"uuid":"667400461","full_name":"BrighterCommand/Rewind","owner":"BrighterCommand","description":"Collates documents from folders to build a multi-version GitBook site","archived":false,"fork":false,"pushed_at":"2023-11-01T13:38:24.000Z","size":773,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-01-11T20:45:31.129Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/BrighterCommand.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}},"created_at":"2023-07-17T12:21:25.000Z","updated_at":"2023-09-04T22:34:30.000Z","dependencies_parsed_at":"2023-07-22T03:15:23.728Z","dependency_job_id":"75112428-8ca3-4744-9d02-a0cd5fc43da9","html_url":"https://github.com/BrighterCommand/Rewind","commit_stats":null,"previous_names":["brightercommand/rewind"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrighterCommand%2FRewind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrighterCommand%2FRewind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrighterCommand%2FRewind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrighterCommand%2FRewind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BrighterCommand","download_url":"https://codeload.github.com/BrighterCommand/Rewind/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241329415,"owners_count":19944984,"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-11-12T20:08:54.710Z","updated_at":"2025-03-01T06:44:27.255Z","avatar_url":"https://github.com/BrighterCommand.png","language":"Go","readme":"# Rewind\nCollates documents from folders to build a multi-version GitBook site\n\n## Versioned Documentation\n\nFor BrighterCommand to support multiple major versions, it needs to be able to support multiple versions of our documentation.\nWith each new major version it is likely that something changes in the documentation but not everything changes. We need GitBook to\noffer at least two versions- current and last. But GitBook does not allow multiple links to the same file within the TOC. This\nmeans that each version must have its own copy of any file in the TOC. If both 9.0.0 and 10.0.0 have the file Introduction.md, then\neach version's TOC must point to a separate copy of the file. \n\nSo to avoid manually \"cutting and pasting\" the common documents into the each version, Rewind will copy the common files to each \nversion followed by the version specific documentation to use with the TOC for each version.\n\n## Directory structure\n\nWe take a directory structure that gives us the shared and versioned documents, and how to fit them into a TOC that covers both\n\nsource\n- root - the root level files for a GitBook project. Readme, Summary, etc\n- shared - the documentation for Brighter or Darker that is common across all versions. .toc.yaml and .md files\n- 9 - the documentation for Brighter or Darker that is specific to V9. .toc.yaml and .md files\n  - _static\\images - any images used by the docs\n- 10 - the documentation for Brighter or Darker that is specific to v10. .toc.yaml and .md files\n  - _static\\images - any images used by the docs\n \nWe then merge shared with each version and build the Summary.md file which from the .toc.yaml files\n\ndocs - the root level files for a GitBook project. Readme, Summary, etc\n- 9 - the docs for v1\n  - _static\\images - any images used by the docs\n- 10 - the docs for v2\n  - _static\\images - any images used by the docs\n\n## Building the documentation\n\nWhen we build the documentation for a version, we copy shared, then the documentation for each version. This means that \nif you have shared and 9.0.0 and 10.0.0, any docs that appear in both 9.0.0 and 10.0.0 should appear in shared. We won't copy \nfrom 9.0.0 to 10.0.0. \n\nThis works to support two versions =\u003e the tip of the spear and the last release. If we want to support documentation for three versions\nthis would get more complicated as we would need to flow documents from one version to the next i.e. 8.0.0 to 9.0.0 to 10.0.0 unless \noverwritten. This is out-of-scope as we have no plans to support three versions right now.\n\n## Table of Contents\n\nFor GitBook we build a [SUMMARY.md](https://docs.gitbook.com/product-tour/git-sync/content-configuration) file.\n\nTo build the SUMMARY.md file we use .toc.yaml files that we locate in the root of any document collection. \nThe .toc.yaml file is a list of files that we want to include in the table of contents. \n\nFiles are grouped by heading (for example Brighter Configuration, Brighter Request Handlers and Middleware Pipelines). \nThis appears in the subsequent markdown file as a level 2 heading.\n\nUnder each heading is a collection of links to the pages in that section of the table of contents.\n\nTo create this in our .toc.yaml file we create a map for each configuration section. The key is the heading and the value. \nFor each link you need to supply: filename, title and indent. The indent is how deeply indented you want the \nfile's entry to be in the table of contents. The indent is optional and defaults to 1. This allows you to nest pages.\n\nAssuming the following .toc.yaml file was located in the root of a v9.0.0 folder\n\n```yaml\n---\nBrighter Configuration:\n  order: 10\n  entries:\n  - name: Getting Started\n    file: GettingStarted.md\n    order: 100\n...\n```\n\nthis will yield the following in the SUMMARY.md file\n\n```markdown\n## Brighter Configuration\n* [Getting Started](/v9.0.0/GettingStarted.md)\n```\n\n### Ordering\n\nOrdering lets you order the sections in the table of contents. For entries it may make sense to use an ordering of 100, \n200, 300, etc. to allow interpolcation of entries within a section in the future. For sections it may make sense to use \n10, 20, 30, etc.\n\nWe need ordering because we can't guarantee the order of the keys in a map. This is because the order of keys in a map\nis not defined in the YAML specification. In practice, most YAML parsers preserve the order of keys. However, we can't\nguarantee that the order will be preserved in the future. So we use an explicit ordering.\n\n### Anchor Links\n\nWe don't support Anchor Links for page links within the TOC in this version. This is because whilst GitBook displays them \nit does not allow them to be navigated. GitBook does show an outline control that indicates the sub-headings. For this\nreason, you should just document whole pages in the TOC.\n\n\n\n\n\n\n\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrightercommand%2Frewind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrightercommand%2Frewind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrightercommand%2Frewind/lists"}