Background: the current system for creating multiple versions of documentation pages can be made easier with plugins, and a different naming convention.
Goals:
Each page should only need to contain version information about itself; not for all past and future versions as well.
Associating multiple versions of a documentation page should not involve having to create folders to group pages of similar versions.
Any version of a documentation page may be compatible with one or more Github branches, or Rubygem versions.
All versions of a documentation page need not have their own entry the nav menu.
How to create a new version of a documentation page (ideally):
Copy the latest version of the page (the one without any versioned suffix) to a file with a versioned suffix.
For example:
cp pages/my_tutorial.md pages/my_tutorial__1.0.md
Update content for the latest version of the doc page (the one without the versioned suffix).
Optional: Override the default version label in the front matter.
For example:
# in pages/my_tutorial.md
version:
# The default label would be "My Tutorial" (gleaned from the filename).
# Here we can change it to include the latest version number.
label: "My Tutorial 1.1"
Strategy:
Instead of using folders to group multiple versions of a given doc page, use an easy-to-read file naming convention.
For example, the following documentation pages would be versions of each other:
pages/my_tutorial.md(latest version)
pages/my_tutorial__1.1.md
pages/my_tutorial__1.0.md
pages/my_tutorial__1.0_with_special_feature.md
Based on this filenaming convention, a plugin can be used to:
Detect which doc pages are versions of each other, by matching the file name before the __x.y.z.md suffix
Create a default label for the version of the doc page by title-izing the file name.
Versions are ordered lexicographically by their version suffix.
The plugin gathers information about all available versions of a given page, and adds that data to the page dynamically. The data is then made available on the Liquid object, as if it had been explicitly included in the page's front matter.
For example, given the filenames above, each Liquid Page object would have version information as if the following had been entered manually in the page's front matter:
versions:
- label : "My Tutorial"
link" : 'pages/my_tutorial.md'
- label: "My Tutorial 1.1"
link: 'pages/my_tutorial__1.1.md'
- label: "My Tutorial 1.0"
link: 'pages/my_tutorial__1.0.md'
- label: "My Tutorial 1.0 With Special Feature"
link: 'pages/my_tutorial__1.0_with_special_feature.md'
So the value here is that we can easily add new versions, without having to create directories or move pages, and without having to retroactively update older versions of pages.
Done when: new versions of existing documentation pages can be created using the How to steps above.
Background: the current system for creating multiple versions of documentation pages can be made easier with plugins, and a different naming convention.
Goals:
How to create a new version of a documentation page (ideally):
Copy the latest version of the page (the one without any versioned suffix) to a file with a versioned suffix.
For example:
Optional: Override the default version label in the front matter.
For example:
Strategy:
Instead of using folders to group multiple versions of a given doc page, use an easy-to-read file naming convention.
For example, the following documentation pages would be versions of each other:
pages/my_tutorial.md(latest version)pages/my_tutorial__1.1.mdpages/my_tutorial__1.0.mdpages/my_tutorial__1.0_with_special_feature.mdBased on this filenaming convention, a plugin can be used to:
__x.y.z.md suffixThe plugin gathers information about all available versions of a given page, and adds that data to the page dynamically. The data is then made available on the Liquid object, as if it had been explicitly included in the page's front matter.
For example, given the filenames above, each Liquid Page object would have version information as if the following had been entered manually in the page's front matter:
So the value here is that we can easily add new versions, without having to create directories or move pages, and without having to retroactively update older versions of pages.
Done when: new versions of existing documentation pages can be created using the How to steps above.