Редиректы

Diplodoc позволяет настраивать редиректы внутри проекта:

• в статической документации — через заголовки страниц;
• в облачной версии — через файл redirects.yaml.

Редиректы в статической документации

Чтобы настроить редирект, в начало исходной страницы добавьте метатеги:

---
metadata:
  - name: redirect
    http-equiv: refresh
    content: '0; url=<путь_к_целевой_странице>'
---

Описание полей:

• name: redirect — имя метатега для обозначения редиректа.
• http-equiv: refresh — обновление страницы браузером.
• content: '0; url=<путь_к_целевой_странице>' — атрибут с параметрами:
  • 0 — задержка в секундах перед редиректом. 0 означает немедленный редирект.
  • url=<путь_к_целевой_странице> — URL-адрес целевой страницы редиректа.

В поле url можно указать:

• Абсолютный путь — полный URL-адрес страницы, на которую нужно сделать редирект.
• Относительный путь — путь от исходной страницы или корня текущего проекта. Например, ../folder/page или /root-folder/page.

Чтобы исходная страница не отображалась в оглавлении, скройте ее в файле toc.yaml:

- href: <путь_к_сходной_странице>.md
  hidden: true

Ограничения

• Не сохраняют якорные ссылки.
• Исходный файл нельзя удалить из проекта.

Пример внешнего редиректа

Редирект с https://diplodoc.com/docs/ru/page-constructor/old-spec/ на https://preview.gravity-ui.com/page-constructor/.

1. Файл /ru/page-constructor/old-spec/index.md:

   ---
   metadata:
     - name: redirect
       http-equiv: refresh
       content: '0; url=https://preview.gravity-ui.com/page-constructor/'
   ---
   

2. Файл /ru/toc.yaml:

   - href: page-constructor/old-spec/index.md
     hidden: true
   

Пример внутреннего проекта

Редирект со страницы ru/settings/old-page.html на страницу ru/settings/new-folder/new-page.html.

1. Файл ru/settings/old-page.md:

   ---
   metadata:
     - name: redirect
       http-equiv: refresh
       content: '0; url=./new-folder/new-page.html'
   ---
   

2. Файл ru/toc.yaml:

   - href: settings/old-page.md
     hidden: true
   

Редиректы в облачной версии

Редиректы в облачной версии можно описать в файле redirects.yaml, который должен быть расположен на одном уровне с конфигурационным файлом .yfm.

Структура файла

Файл redirects.yaml состоит из:

• языковых секций, которые содержат редиректы для отдельных языков документации;
• секции common с редиректами для всех языков документации.

Указывать редиректы вне секции нельзя.

Особенности настройки

• Редиректы настраиваются только внутри документационного проекта.

• Не поддержана работа с якорными ссылками.

• В секции common пути указываются относительно корня проекта. В языковых секциях пути указываются относительно языковых папок без их прямого указания в пути. Для директорий в конце добавляется символ /. Указывать расширение .md не требуется. Пример файла.

• Можно использовать регулярные выражения.

  Пример кода

  - from: /concepts/referral-(.*)
    to: /index
  

Пример redirects.yaml

# Секция редиректов для отдельных языков документации
ru:
    - from: /entry1
      to: /folder1/entry1
en:
    - from: /entry2
      to: /folder2/entry2
# Секция common
common:
    - from: /entry3
      to: /folder3/entry3

Примеры для файлов

- from: /pricing
  to: /pricing-info

- from: /details/(.*)-mini
  to: /details/$1-mini2

- from: feedback
  to: /troubleshooting/feedback

- from: /devices/third-party/troubleshooting/reset
  to: /devices/index

- from: /phones/assistance
  to: /phones/help/index

- from: /devices/index
  to: /index

- from: /old/concepts/([^/]+)
  to: /index

Примеры для каталогов

- from: /devices/settings/
  to: /phones/settings/

- from: /(.*)/folder/
  to: /$1/renamed-folder/