Spec Versioning

.github/workflows/pages.yml

@@ -3,6 +3,8 @@ on:
     push:
         branches:
             - main
+        tags:
+            - '*'
     workflow_dispatch:
 
 # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
@@ -13,7 +15,7 @@ concurrency:
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
-    contents: read
+    contents: write
     pages: write
     id-token: write
 
@@ -30,19 +32,20 @@ jobs:
             sudo apt update -q
             sudo apt install -yy python3 python3-pip graphviz
             pip install -r tools/requirements.txt
+            git config user.name "Lottie CI"
+            git config user.email "lottie@example.com"
+            git fetch origin gh-pages --depth=1
       -
-        name: Docs
-        run: make
-      -
-        name: Setup Pages
-        uses: actions/configure-pages@v4
-      -
-        name: Upload artifact
-        uses: actions/upload-pages-artifact@v2
-        with:
-            path: 'site'
+        name: Dev Docs
+        if: ${{ github.ref == 'refs/heads/main' }}
+        run: |
+            make lottie.schema.json
+            tools/mike deploy dev --push
       -
-        name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v3
-
+        name: Docs
+        if: ${{ github.ref != 'refs/heads/main' }}
+        env:
+          RELEASE_VERSION: ${{ github.ref_name }}
+        run: |
+            make lottie.schema.json
+            tools/mike deploy "$RELEASE_VERSION" --push

.github/workflows/tag-latest.yml

@@ -0,0 +1,44 @@
+name: Tag Latest
+on:
+    workflow_dispatch:
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+    contents: write
+    pages: write
+    id-token: write
+
+jobs:
+  tag-latest:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Failsafe
+        if: ${{ ! startsWith(github.ref, 'refs/tags/') }}
+        run: |
+            echo "Only run on tags" >&2
+            false
+      -
+        name: Checkout
+        uses: actions/checkout@v4
+      -
+        name: Setup
+        run: |
+            sudo apt update -q
+            sudo apt install -yy python3 python3-pip graphviz
+            pip install -r tools/requirements.txt
+            git config user.name "Lottie CI"
+            git config user.email "lottie@example.com"
+            git fetch origin gh-pages --depth=1
+            make lottie.schema.json
+      -
+        name: Tag Latest
+        env:
+          RELEASE_VERSION: ${{ github.ref_name }}
+        run: tools/mike alias -u "$RELEASE_VERSION" latest --push
+

docs/validator/index.md

@@ -4,7 +4,7 @@ disable_toc: 1
 # Lottie Validator
 
 <script src="https://cdnjs.cloudflare.com/ajax/libs/ajv/8.16.0/ajv2020.min.js" integrity="sha512-OunSQfwE+NRzXE6jEJfFCyVkFQgMOk+oxD34iU8Xc21cUYfFH5TKBc7Z3RqKC4EW1tlllWIIOdq2Kf5F/5wKOw==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
-<script src="{{url}}/js/validator.js"></script>
+<script src="../js/validator.js"></script>
 
 <style>
 .hidden {

mkdocs.yml

@@ -44,6 +44,8 @@ nav:
             - editing/extensions.md
 plugins:
     - search
+    - mike:
+        version_selector: true
     - print-site:
         add_table_of_contents: false
         enumerate_headings_depth: 3

tools/lottie_markdown.py

@@ -9,7 +9,6 @@
 from markdown.extensions import Extension
 from markdown.inlinepatterns import InlineProcessor
 from markdown.blockprocessors import BlockProcessor
-from markdown.preprocessors import Preprocessor
 from markdown.util import HTML_PLACEHOLDER_RE, AtomicString
 from mkdocs.utils import get_relative_url
 
@@ -708,18 +707,6 @@ def get_url(md, path, anchor=None, src_uri=True):
     return url
 
 
-class BaseUrl(Preprocessor):
-    def __init__(self, md):
-        super().__init__(md)
-        self.base_url = None
-
-    def run(self, lines):
-        if self.base_url is None:
-            pages = get_page_processor(self.md)
-            self.base_url = pages.config["site_url"]
-        return list(map(lambda line: line.replace("{{url}}", self.base_url), lines))
-
-
 class LottieBlock(BlockProcessor):
     def __init__(self, md):
         self.md = md
@@ -1236,8 +1223,6 @@ def extendMarkdown(self, md: Markdown):
         md.parser.blockprocessors.register(SchemaEnum(md, ts), "schema_enum", 175)
         md.parser.blockprocessors.register(EditorExample(md.parser), "editor_example", 175)
 
-        md.preprocessors.register(BaseUrl(md), "base_url", 1000)
-
 
 def makeExtension(**kwargs):
     return LottieExtension(**kwargs)

tools/mike

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+
+import os
+import sys
+import pathlib
+import subprocess
+
+source_dir = pathlib.Path(__file__).parent.parent
+os.environ["PYTHONPATH"] = str(source_dir / "tools")
+sys.exit(subprocess.call(["mike"] + sys.argv[1:] + ["-F", source_dir / "mkdocs.yml"]))
+

tools/requirements.txt

@@ -6,3 +6,5 @@ graphviz==0.20.1
 latex2mathml==3.77.0
 # Used for link validations
 lxml==4.9.3
+# Versioning
+mike==2.1.3

tools/theme/css/version-select.css

@@ -0,0 +1,15 @@
+@media only screen and (max-width:76.1875em) {
+    #version-selector {
+        padding: .6rem .8rem;
+    }
+}
+
+.navbar-header {
+    display: flex;
+    align-items: center;
+}
+
+.version-selector {
+    height: fit-content;
+    display: inline-block;
+}

tools/theme/js/version-select.js

@@ -0,0 +1,87 @@
+window.addEventListener("DOMContentLoaded", function() {
+  function expandPath(path) {
+    // Get the base directory components.
+    var expanded = window.location.pathname.split("/");
+    expanded.pop();
+    var isSubdir = false;
+
+    path.split("/").forEach(function(bit, i) {
+      if (bit === "" && i === 0) {
+        isSubdir = false;
+        expanded = [""];
+      } else if (bit === "." || bit === "") {
+        isSubdir = true;
+      } else if (bit === "..") {
+        if (expanded.length === 1) {
+          // We must be trying to .. past the root!
+          throw new Error("invalid path");
+        } else {
+          isSubdir = true;
+          expanded.pop();
+        }
+      } else {
+        isSubdir = false;
+        expanded.push(bit);
+      }
+    });
+
+    if (isSubdir)
+      expanded.push("");
+    return expanded.join("/");
+  }
+
+  // `base_url` comes from the base.html template for this theme.
+  var ABS_BASE_URL = expandPath(base_url);
+  var CURRENT_VERSION = ABS_BASE_URL.match(/\/([^\/]+)\/$/)[1];
+
+  function makeSelect(options) {
+    var select = document.createElement("select");
+    select.classList.add("form-control");
+
+    options.forEach(function(i) {
+      var option = new Option(i.text, i.value, undefined,
+                              i.selected);
+      select.add(option);
+    });
+
+    return select;
+  }
+
+  fetch(ABS_BASE_URL + "../versions.json").then((response) => {
+    if ( response.status != 200 )
+      return [];
+    return response.json();
+  }).then((versions) => {
+    if ( versions.length == 0 )
+      return;
+    var realVersion = versions.find(function(i) {
+      return i.version === CURRENT_VERSION ||
+             i.aliases.includes(CURRENT_VERSION);
+    }).version;
+
+    var select = makeSelect(versions.filter(function(i) {
+      return i.version === realVersion || !i.properties || !i.properties.hidden;
+    }).map(function(i) {
+      var title = i.title;
+      if ( i.aliases.length )
+        title += ` (${i.aliases.join(", ")})`;
+      return {text: title, value: i.version,
+              selected: i.version === realVersion};
+    }));
+    select.addEventListener("change", function(event) {
+      window.location.href = ABS_BASE_URL + "../" + this.value + "/";
+    });
+
+    var container = document.createElement("div");
+    container.id = "version-selector";
+    container.appendChild(select);
+
+    var title = document.querySelector(".navbar-brand");
+    if (title.parentNode.classList.contains("navbar-header")) {
+      // var height = window.getComputedStyle(title).getPropertyValue("height");
+      // container.style.height = height;
+    }
+
+    title.parentNode.insertBefore(container, title.nextSibling);
+  });
+});

tools/theme/main.html

@@ -27,8 +27,10 @@
     <link href="{{ 'css/lottie-theme.css'|url }}" rel="stylesheet">
 
     <script>
-        const base_url = "{{ ''|url }}";
+        var base_url = {{ base_url | tojson }};
     </script>
+    <script src="{{ 'js/version-select.js'|url }}"></script>
+    <link href="{{ 'css/version-select.css'|url }}" rel="stylesheet">
 
 {% endblock %}