Repository files navigation

Collates documents from folders to build a multi-version GitBook site

For BrighterCommand to support multiple major versions, it needs to be able to support multiple versions of our documentation.With each new major version it is likely that something changes in the documentation but not everything changes. We need GitBook tooffer at least two versions- current and last. But GitBook does not allow multiple links to the same file within the TOC. Thismeans 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, theneach version's TOC must point to a separate copy of the file.

So to avoid manually "cutting and pasting" the common documents into the each version, Rewind will copy the common files to eachversion followed by the version specific documentation to use with the TOC for each version.

We take a directory structure that gives us the shared and versioned documents, and how to fit them into a TOC that covers both

source

• root - the root level files for a GitBook project. Readme, Summary, etc
• shared - the documentation for Brighter or Darker that is common across all versions. .toc.yaml and .md files
• 9 - the documentation for Brighter or Darker that is specific to V9. .toc.yaml and .md files
  • _static\images - any images used by the docs
• 10 - the documentation for Brighter or Darker that is specific to v10. .toc.yaml and .md files
  • _static\images - any images used by the docs

We then merge shared with each version and build the Summary.md file which from the .toc.yaml files

docs - the root level files for a GitBook project. Readme, Summary, etc

• 9 - the docs for v1
  • _static\images - any images used by the docs
• 10 - the docs for v2
  • _static\images - any images used by the docs

When we build the documentation for a version, we copy shared, then the documentation for each version. This means thatif 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 copyfrom 9.0.0 to 10.0.0.

This works to support two versions => the tip of the spear and the last release. If we want to support documentation for three versionsthis 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 unlessoverwritten. This is out-of-scope as we have no plans to support three versions right now.

For GitBook we build aSUMMARY.md file.

To build the SUMMARY.md file we use .toc.yaml files that we locate in the root of any document collection.The .toc.yaml file is a list of files that we want to include in the table of contents.

Files are grouped by heading (for example Brighter Configuration, Brighter Request Handlers and Middleware Pipelines).This appears in the subsequent markdown file as a level 2 heading.

Under each heading is a collection of links to the pages in that section of the table of contents.

To create this in our .toc.yaml file we create a map for each configuration section. The key is the heading and the value.For each link you need to supply: filename, title and indent. The indent is how deeply indented you want thefile's entry to be in the table of contents. The indent is optional and defaults to 1. This allows you to nest pages.

Assuming the following .toc.yaml file was located in the root of a v9.0.0 folder

---Brighter Configuration:order:10entries:  -name:Getting Startedfile:GettingStarted.mdorder:100...

this will yield the following in the SUMMARY.md file

##Brighter Configuration*[Getting Started](/v9.0.0/GettingStarted.md)

Ordering lets you order the sections in the table of contents. For entries it may make sense to use an ordering of 100,200, 300, etc. to allow interpolcation of entries within a section in the future. For sections it may make sense to use10, 20, 30, etc.

We need ordering because we can't guarantee the order of the keys in a map. This is because the order of keys in a mapis not defined in the YAML specification. In practice, most YAML parsers preserve the order of keys. However, we can'tguarantee that the order will be preserved in the future. So we use an explicit ordering.

We don't support Anchor Links for page links within the TOC in this version. This is because whilst GitBook displays themit does not allow them to be navigated. GitBook does show an outline control that indicates the sub-headings. For thisreason, you should just document whole pages in the TOC.