Versioned Documentation

[froschdesign]

Problem

Some component documentations already includes descriptions and pages for different component versions. This ends up in a very long sub-navigation and duplications of navigations entries.

Example

zend-expressive with 3 versions: https://docs.zendframework.com/zend-expressive

Goals for Improvement

• add a version selector
• only show pages of the currently selected version in the sub-navigation
• output a notice if the currently selected version is not the latest
• backward compatibility:
  • no changes in URLs
  • without any changes (in the MkDocs configuration), the result of the rendering must be the same as before

Suggestion

The current idea is based on an extension of the MkDocs configuration file (mkdocs.yml).

New is the extra level in pages for the version number and the section extra.

Example (excerpt)

docs_dir: docs/book
site_dir: docs/html
pages:
    - Home: index.md
    - v3:
      - "Quick Start": v3/quick-start.md
      - Hydrators:
        - "ArraySerializable": v3/hydrators/array-serializable.md
        - "ObjectProperty": v3/hydrators/object-property.md
        - "Reflection": v3/hydrators/reflection.md
        - "ClassMethods": v3/hydrators/class-methods.md
        - "Delegating": v3/hydrators/delegating.md
        - "Aggregate": v3/hydrators/aggregate.md
      - Strategies:
        - …
      - "Application Integration":
        - "Usage in a zend-mvc-based Application": v3/application-integration/zend-mvc.md
      - Migration:
        - "Migration from version 2": v3/migration.md
    - v2:
      - "Quick Start": v2/quick-start.md
      - Reference:
        - "Filters": v2/filter.md
        - …
    - "_hidden-legacy-page-links":
        - "_quick_start": quick-start.md
        - …
site_name: zend-hydrator
site_description: "Serialize objects to arrays, and vice versa"
repo_url: 'https://github.com/zendframework/zend-hydrator'
markdown_extensions:
  - markdown.extensions.codehilite:
      use_pygments: False
edit_uri: edit/master/${DOCS_DIR}/
extra:
  current_version: v3
  versions:
    - v3
    - v2

Screenshots

To-do

• Update the Jinja2 templates
• Add CSS for version selector
• Test component with different versions
• Test component without versions

---

Comments and suggestions are welcome!

[froschdesign]

ping @weierophinney @settermjd @xtreamwayz

[geerteltink]

Where is the PR so I can merge it now.

[weierophinney]

Totally want this. 👍

[froschdesign]

Fixed with #87