Add selector-labels extension (#28)

extensions/antora/selector-labels/README.md

@@ -0,0 +1,51 @@
+# selector-labels
+
+Use the `selector-labels` extension to add text to component versions in the version selector.
+
+
+## Usage
+
+
+1. Install the extension: `npm i @neo4j-antora/selector-labels`
+2. Add the extension in a playbook
+
+    ```
+    antora:
+      extensions:
+      - require: "@neo4j-antora/selector-labels.js"
+    ```
+
+3. Add `lts: true` or `current: true` to a component descriptor file (_antora.yml_). The ui-bundle will display the corresponding text, `(LTS)` or `(Current)` after the component name and version in the version selector.
+
+
+## Config
+
+You can define a custom list of attributes in the playbook.
+
+If you do not define any attributes, the default values are used.
+The default values are equivalent to adding the following to the playbook:
+
+```
+antora:
+  extensions:
+  - require: "@neo4j-antora/selector-labels.js"
+    current:
+      selector_text: '(Current)'
+      unique: true
+    lts:
+      selector_text: '(LTS)'
+```
+
+In the default configuration, text is added in the version selector, after the component name and version, to 'Current' and 'LTS' releases.
+
+By default, `current` is given the attribute value `unique: true`, meaning that for a given component, only one version can be considered 'Current'. An error is logged for a component if more than one version has a unique attribute defined in its _antora.yml_ file.
+
+
+## Using the CLI to add the extension
+
+Although you will usually want to add the extension to a playbook, you can add it by using the Antora CLI.
+You can do this with the `--extension` option:
+
+```
+--extension <PATH TO EXTENSION>
+```

extensions/antora/selector-labels/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@neo4j-antora/selector-labels",
+  "version": "0.1.0",
+  "description": "Add text to component versions in a version selector",
+  "main": "selector-labels.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "antora"
+  ],
+  "author": "Neo4j",
+  "license": "MIT"
+}

extensions/antora/selector-labels/selector-labels.js

@@ -0,0 +1,60 @@
+// Add an LTS value to the component version object in the contentCatalog
+// to mark a component version as an LTS release in the source
+// add lts:true to the relevant antora.yml file
+
+module.exports.register = function ({ config }) {
+  const logger = this.getLogger('selector-labels')
+  this.on('navigationBuilt', ({ contentCatalog }) => {
+
+    const defaultConfig = [
+      [ 'current', { selectorText: '(Current)', unique: true } ],
+      [ 'lts', { selectorText: '(LTS)' } ]
+    ]
+
+    const data = Object.entries(config).length > 0 ? Object.entries(config) : defaultConfig
+    const files = contentCatalog.findBy({ family: 'nav' })
+
+    var selectorLabels = []
+    data.forEach(([attr, properties]) => {
+
+      const componentVersions = files.reduce((v, file) => {
+        if ('origin' in file.src && file.src.origin.descriptor[attr]) {
+          const key = file.src.version + '@' + file.src.component
+          v.indexOf(key) === -1 ? v.push(key) : null
+        } 
+        return v;
+      }, []);
+
+      selectorLabels.push({
+        name: attr,
+        properties: properties,
+        componentVersions: componentVersions
+      })
+
+
+    })
+
+    selectorLabels.forEach((label) => {
+      label.componentVersions.forEach((entry) => {
+        const [version, component] = entry.split('@')
+        const componentVersion = contentCatalog.getComponentVersion(component, version)
+        componentVersion.selectorText = (componentVersion.selectorText || '').concat(' ' + label.properties.selectorText).trim()
+        componentVersion[label.name] = true
+        label.componentsMarked = (label.componentsMarked || {})
+        label.componentsMarked[component] = (label.componentsMarked[component] || []).concat([version])
+        logger.info('Marked %s@%s as %s', version, component, label.properties.selectorText)
+      })
+
+    })
+
+    // Check for components with multiple attrs where attr is marked as unique in config
+    selectorLabels.filter(label => label.properties.unique).forEach((label) => {
+      Object.keys(label.componentsMarked).forEach((component) => {
+        if (label.componentsMarked[component].length > 1) {
+          logger.error('Component %s has multiple %s versions: %s', component, label.name, label.componentsMarked[component].join(', '))
+        }
+      })
+    })
+
+  })
+}