Skip to content

Allow book versions to be defined in a more flexible way

Created by: seanmadsen

Our current config schema

The way this app currently works, you define a book like this:

name: User Guide
langs:
  en:
    repo: 'https://github.com/civicrm/civicrm-user-guide'
    latest: master
    stable: 4.7
    history:
      - 4.6

End-user example from Symfony

There are a number of limitations with our current approach. For the sake of time, I won't summarize them all. But I will offer an example of the end-user experience of choosing a version within Symfony's documentation:

screenshot13

I like the way this works. When you click on "3.2 / Current" you're taken to /doc/current/. If you manually enter the URL /doc/3.2/ you get redirected to /doc/current. Very slick. Very usable.

Proposed new config schema

I want to change it to this:

name: User Guide
default_language: en
languages:
  en:
    repo: 'https://github.com/civicrm/civicrm-user-guide'
    default_version: 4.7
    watchers:
      - sean@seanmadsen.com
    versions:
      4.7:                    # This is stored as $slug
        name: 4.7 / Current   # If omitted, use $slug
        path: current         # If omitted, use a URL-safe version of $slug
        branch: master        # If omitted, use $slug
        visible: true         # If omitted, use "true"
        maintained: true      # If omitted, use "true"
        redirects:            # These are not displayed anywhere
          - latest
      4.6:
        branch: 4.6
        name: 4.6 / LTS
        redirects:
          - lts
      4.5:
        branch: 4.5
        visible: false
        maintained: false

Here's what each of those settings would actually do:

  • slug - basically just used to organize the settings within the yaml file
  • name - this is what the user sees when choosing between different versions, and at the top of every page when viewing the book
  • path - this is used for the version component of the URL
  • branch - tells us what branch to use in the git repo
  • visible - when true, display this version in lists of different versions presented to the user. When false, don't display this version in navigation, but still allow its content to be published and viewed
  • maintained - when this is false, display something like "(unmaintained)" to the user in various contexts such as choosing between different versions and (possible) when viewing the book
  • redirects - when a user requests a URL with one of the listed redirects in place of path, the app will redirect the user to the correct URL that uses path. Both branch and slug will automatically function as redirects when their values differ from path.

I'm curious to hear feedback from others about this proposal. If I don't hear any concerns within 5 days, I'll begin the work to implement this proposal.