New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Versioned Documentation #71

froschdesign opened this Issue Dec 1, 2018 · 3 comments


None yet
3 participants

froschdesign commented Dec 1, 2018


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.


zend-expressive with 3 versions:

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


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
    - Home:
    - v3:
      - "Quick Start": v3/
      - Hydrators:
        - "ArraySerializable": v3/hydrators/
        - "ObjectProperty": v3/hydrators/
        - "Reflection": v3/hydrators/
        - "ClassMethods": v3/hydrators/
        - "Delegating": v3/hydrators/
        - "Aggregate": v3/hydrators/
      - Strategies:
      - "Application Integration":
        - "Usage in a zend-mvc-based Application": v3/application-integration/
      - Migration:
        - "Migration from version 2": v3/
    - v2:
      - "Quick Start": v2/
      - Reference:
        - "Filters": v2/
    - "_hidden-legacy-page-links":
        - "_quick_start":
site_name: zend-hydrator
site_description: "Serialize objects to arrays, and vice versa"
repo_url: ''
  - markdown.extensions.codehilite:
      use_pygments: False
edit_uri: edit/master/${DOCS_DIR}/
  current_version: v3
    - v3
    - v2


screenshot_2018-12-01 home - zend-hydrator
screenshot_2018-12-01 quick start - zend-hydrator


  • Update the Jinja2 templates
  • Add CSS for version selector

Comments and suggestions are welcome!


This comment has been minimized.


froschdesign commented Dec 1, 2018


This comment has been minimized.


xtreamwayz commented Dec 1, 2018

Where is the PR so I can merge it now.


This comment has been minimized.


weierophinney commented Dec 5, 2018

Totally want this. 👍

@froschdesign froschdesign added this to the 0.7.0 milestone Dec 8, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment