Redirects

Diplodoc allows you to configure redirects within a project:

• in static documentation — via page headers;
• in the cloud version — via the redirects.yaml file.

Redirects in static documentation

To configure a redirect, add meta tags to the beginning of the source page:

---
metadata:
  - name: redirect
    http-equiv: refresh
    content: '0; url=<path_to_target_page>'
---

Field descriptions:

• name: redirect — the name of the meta tag to indicate a redirect.
• http-equiv: refresh — page refresh by the browser.
• content: '0; url=<path_to_target_page>' — an attribute with parameters:
  • 0 — delay in seconds before the redirect. 0 means an immediate redirect.
  • url=<path_to_target_page> — the URL of the redirect target page.

In the url field, you can specify:

• An absolute path — the full URL of the page to which the redirect should be made.
• A relative path — the path from the source page or the root of the current project. For example, ../folder/page or /root-folder/page.

To prevent the source page from appearing in the table of contents, hide it in the toc.yaml file:

- href: <path_to_source_page>.md
  hidden: true

Limitations

• Anchor links are not preserved.
• The source file cannot be deleted from the project.

Example of an external redirect

Redirect from https://diplodoc.com/docs/ru/page-constructor/old-spec/ to https://preview.gravity-ui.com/page-constructor/.

1. File /ru/page-constructor/old-spec/index.md:

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

2. File /ru/toc.yaml:

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

Example of an internal project

Redirect from the page ru/settings/old-page.html to the page ru/settings/new-folder/new-page.html.

1. File ru/settings/old-page.md:

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

2. File ru/toc.yaml:

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

Redirects in the cloud version

Redirects in the cloud version can be described in the redirects.yaml file, which must be located at the same level as the configuration file .yfm.

File structure

The redirects.yaml file consists of:

• language sections that contain redirects for individual documentation languages;
• the common section with redirects for all documentation languages.

Redirects cannot be specified outside a section.

Configuration specifics

• Redirects are configured only within the documentation project.

• Anchor links are not supported.

• In the common section, paths are specified relative to the project root. In language sections, paths are specified relative to the language folders without including them directly in the path. For directories, a / symbol is added at the end. Specifying the .md extension is not required. Example file.

• Regular expressions can be used.

  Code example

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

Example redirects.yaml

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

Examples for files

- 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

Examples for directories

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

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