Use frontmatter to link users to previous versions of the documentation

[bmorelli25]

Summary

Many documentation files include a mapped_pages frontmatter key—For example: https://github.com/search?q=repo%3Aelastic%2Fdocs-content%20mapped_pages&type=code. This key lists legacy documentation URLs that served as source material when creating the current content.

Goal

Help users easily access the older versions of a given doc.

Implementation

• If a mapped_pages key exists, display a "Previous versions" link in the right-hand column.
• The link should point to the first URL in the mapped_pages array. (we can likely make this experience better in a follow-up PR)

Considerations

Mapped URLs use current:
Mapped pages use /current/ in the URL, which will eventually redirect to the new V3 docs. We therefore cannot use the mapped pages URLs as-is. Before generating the previous version link, we need to update these links accordingly:

For the following links, current should be updated to the version listed:

[edit: removed] see @colleenmcginnis's comment below instead

For the following links, no previous version documentation exists, so we should not add a "Previous versions" link to these pages:

[edit: removed] see @colleenmcginnis's comment below instead

All remaining mapped pages are stack-versioned. We should replace current with 8.17 for these links.

[colleenmcginnis]

In case it's helpful, here's the list I was using to generate redirects (undefined means the AsciiDoc docs are not versioned):

const stack = '8.18'

export default {
  'en/apm/agent/android': '0.x',
  'en/apm/agent/dotnet': '1.x',
  'en/apm/agent/go': '2.x',
  'en/apm/agent/swift': '1.x',
  'en/apm/agent/java': '1.x',
  'en/apm/agent/nodejs': '4.x',
  'en/apm/agent/php': undefined,
  'en/apm/agent/python': '6.x',
  'en/apm/agent/ruby': '4.x',
  'en/apm/agent/rum-js': '5.x',
  'en/apm/lambda': undefined,
  'en/apm/attacher': undefined,
  'en/beats/auditbeat': stack,
  'en/beats/devguide': stack,
  'en/beats/filebeat': stack,
  'en/beats/functionbeat': stack,
  'en/beats/heartbeat': stack,
  'en/beats/journalbeat': stack,
  'en/beats/libbeat': stack,
  'en/beats/loggingplugin': stack,
  'en/beats/metricbeat': stack,
  'en/beats/packetbeat': stack,
  'en/beats/topbeat': stack,
  'en/beats/winlogbeat': stack,
  'en/cloud': undefined,
  'en/cloud-enterprise': '3.7',
  'en/cloud-heroku': undefined,
  'en/cloud-on-k8s': '2.16',
  'en/elasticsearch/client/curator': '8.0',
  'en/ecctl': '1.14',
  'en/ecs': stack,
  'en/ecs-logging/dotnet': undefined,
  'en/ecs-logging': undefined,
  'en/ecs-logging/go-logrus': undefined,
  'en/ecs-logging/go-zap': undefined,
  'en/ecs-logging/go-zerolog': undefined,
  'en/ecs-logging/java': '1.x',
  'en/ecs-logging/nodejs': undefined,
  'en/ecs-logging/php': undefined,
  'en/ecs-logging/python': undefined,
  'en/ecs-logging/ruby': undefined,
  'en/elasticsearch/client/eland': undefined,
  'en/esf': undefined,
  'en/elasticsearch/reference': stack,
  'en/elasticsearch/hadoop': stack,
  'en/elasticsearch/client/java-api-client': stack,
  'en/elasticsearch/client/javascript-api': stack,
  'en/elasticsearch/client/net-api': stack,
  'en/elasticsearch/client/php-api': stack,
  'en/elasticsearch/client/python-api': stack,
  'en/elasticsearch/client/rust-api': stack,
  'en/elasticsearch/client/ruby-api': stack,
  'en/elasticsearch/client/go-api': stack,
  'en/integrations': undefined,
  'en/integrations-developer': undefined,
  'en/kibana': stack,
  'en/logstash': stack,
  'en/logstash-versioned-plugins': undefined,
  'en/search-ui': undefined,
  'en/security': stack,
  'en/starting-with-the-elasticsearch-platform-and-its-solutions': stack,
  'en/observability': stack,
  'en/elasticsearch/painless': stack,
}

[bmorelli25]

Thank you! Very helpful

[colleenmcginnis]

FYI in my testing today I had to update 'en/ecs': stack to 'en/ecs': '8.17' because there is no 8.18 branch. I'm not sure if they are planning to make one ahead of release.