docs: format page reform

ethanresnick · ethanresnick · commit bba04ae0044a · 2018-12-02T15:51:32.000-05:00
The `/format/upcoming/` url still exists (in case it’s ever necessary
to reference “the next version, whatever that may be at the time the
link is followed”). However, it now simply redirects to `/format/1.1/`
rather than having its own content. It’s status content previously was
a bit confusing, and there wasn’t much reason for it to be a dedicated
page.

Additionally, it was confusing to have two links to v1.1 in the version
picker (the upcoming link and the 1.1 permalink). So, now, the version
picker excludes a separate permalink entry for v1.1, and instead has
the picker entry for the “Upcoming spec” simply go to the
`/format/1.1/` page.
diff --git a/_format/1.1/index.md b/_format/1.1/index.md
@@ -1,5 +1,7 @@
 ---
 version: 1.1
+status: rc
+release_date: 2019-01-31
 ---
 
 ## <a href="#introduction" id="introduction" class="headerlink"></a> Introduction
diff --git a/_format/upcoming/index.md b/_format/upcoming/index.md
@@ -1,17 +1,8 @@
 ---
-is_upcoming_version: true
-status: rc
-release_date: 2019-01-31
+# Note: We have to do a `redirect_to` here rather than a redirect_from
+# in the file for the latest spec version, as the latter causes jekyll 
+# generate a redirect to `/format/{version}/index.html`, which is an ugly
+# and non-canonical url, and jekyll's url config settings aren't flexible
+# enough to prevent this. 
+redirect_to: /format/1.1/
 ---
-{% for spec_draft in site.format %}
-  {% if spec_draft.version > site.latest_version and spec_draft.path contains 'index' %}
-    {% comment %}
-      The line below must be outdented (ugly as that is) or it will be parsed
-      differently, since indentation can be significant in markdown (e.g. to
-      indicate code blocks).
-    {% endcomment %}
-
-{{ spec_draft.content }}
-
-  {% endif %}
-{% endfor %}
diff --git a/_includes/status.md b/_includes/status.md
@@ -5,7 +5,6 @@
 
 {% assign version = include.version %}
 {% assign is_latest_version_page = include.is_latest_version %}
-{% assign is_upcoming_version_page = include.is_upcoming_version %}
 {% assign status = include.status %}
 
 ## <a href="#status" id="status" class="headerlink"></a> Status
@@ -24,26 +23,20 @@
   always be backwards compatible** using a _never remove, only add_ strategy.
   Additions can be proposed in our [discussion forum](http://discuss.jsonapi.org/).
 
-{% elsif is_upcoming_version_page %}
-  This page presents the **{% if status == "rc" %}release candidate{% else %}
-  working draft{% endif %}** for the next version of JSON:API, which is 
-  expected to be {{ site.latest_version|plus:0.1 }}. {% if status != "rc" %}
-  As a draft, the content on this page is subject to change.{% else %}As a 
-  release candidate, the content on this page is unlikely to change. However, 
-  some changes may still occur if implementation experience proves that they are 
-  necessary before this version is finalized.{% endif %}
+{% elsif version and version > site.latest_version %}
+  This page will always present the most recent text for JSON:API v{{ site.latest_version|plus:0.1 }}.
+  Version {{ site.latest_version|plus:0.1 }} is a **{% if status == "rc" %}release 
+  candidate{% else %}working draft{% endif %}**. As such, the content on this 
+  page {% if status != "rc" %}is subject to change.{% else %}is unlikely to 
+  change. However, some changes may still occur if implementation experience 
+  proves that they are necessary before this version is finalized.{% endif %}
 
   {% if include.release_date %}
-  This version is expected to be finalized and released on 
-  **{{ include.release_date | date: "%B %e, %Y" }}** (provided there are two compliant implementations by that date; if not the release will wait until such implementations exist to prove its viability).
+  This version is expected to be finalized and released on **{{ include.release_date | date: "%B %e, %Y" }}** 
+  (provided there are two compliant implementations by that date; if not the 
+  release will wait until such implementations exist to prove its viability).
   {% endif %}
 
-
-{% elsif version and version > site.latest_version %}
-  This page will always present the most recent text for JSON:API
-  v{{ site.latest_version|plus:0.1 }}. Version {{ site.latest_version|plus:0.1 }}
-  has not been finalized, so the text here may change.
-
 {% elsif version and version == site.latest_version %}
   This page presents an archived copy of JSON:API version {{ version }}. None
   of the normative text on this page will change. **Subsequent versions of
@@ -55,7 +48,6 @@
   of the normative text on this page will change. While {{ version }} is no
   longer the [latest version](/format/) of JSON:API, **new versions will remain
   compatible with this one**, as JSON:API uses a _never remove, only add_ strategy.
-
 {% endif %}
 
 {% comment %}
diff --git a/_includes/title_for_version.md b/_includes/title_for_version.md
@@ -13,14 +13,10 @@
 {% endcomment %}
 {% assign version = include.version %}
 {% assign is_latest_version_page = include.is_latest_version %}
-{% assign is_upcoming_version_page = include.is_upcoming_version %}
 
 {% if is_latest_version_page %}
   Latest Specification (v{{ site.latest_version }})
 
-{% elsif is_upcoming_version_page %}
-  Draft for Next Specification Release
-
 {% elsif version and version > site.latest_version %}
   Specification v{{site.latest_version|plus:0.1}} (Still in Development)
 
diff --git a/_layouts/page.html b/_layouts/page.html
@@ -13,7 +13,7 @@
 
     {% if page.is_spec_page %}
       {% capture page_title %}
-        {% include title_for_version.md is_latest_version=page.is_latest_version is_upcoming_version=page.is_upcoming_version version=page.version %}
+        {% include title_for_version.md is_latest_version=page.is_latest_version version=page.version %}
       {% endcapture %}
     {% else %}
       {% assign page_title = page.title %}
@@ -53,15 +53,15 @@ <h2>A specification for building APIs in JSON</h2>
                     Latest Version (v{{ site.latest_version }})
                   </option>
                   <option
-                    value="/format/upcoming/"
-                    {% if page.is_upcoming_version %}selected{% endif %}
+                    value="/format/{{ site.latest_version|plus:0.1 }}/"
+                    {% if page.version > site.latest_version %}selected{% endif %}
                   >
                     Upcoming Version (v{{ site.latest_version|plus:0.1 }})
                   </option>
                   <optgroup label="Old Versions/Permalinks">
                     {% assign sorted_formats = site.format|sort:'version' %}
                     {% for spec_draft in sorted_formats %}
-                      {% if spec_draft.version and spec_draft.path contains 'index' %}
+                      {% if spec_draft.version <= site.latest_version and spec_draft.path contains 'index' %}
                         <option value="/format/{{spec_draft.version}}"
                           {% if page.version == spec_draft.version %}selected{% endif%}
                         >
@@ -87,7 +87,7 @@ <h1>
         <section>
           {% if page.is_spec_page %}
             {% capture status %}
-              {% include status.md release_date=page.release_date status=page.status version=page.version is_latest_version=page.is_latest_version is_upcoming_version=page.is_upcoming_version %}
+              {% include status.md release_date=page.release_date status=page.status version=page.version is_latest_version=page.is_latest_version %}
             {% endcapture %}
             {{ status|strip|markdownify }}
           {% endif %}
