hugo: move content files, use filesystem-based navigation

[dvdksn]

This PR:

• Moves all the content to the manuals section under /content, while keeping the original URL paths, and also updating relative links.
• Changes how the sidebar gets generated, from data/toc.yaml to a filesystem-based navigation
• Adds/updates section pages, titles, and assigns page-weights to make the sidebar appear correctly when rendered using the filesystem-based strategy

Note

There is very little user-facing impact from this PR.

Description

The move of content files from ./content/* to ./content/manuals/* without breaking permalinks is achieved using tokens in the url front matter key, stripping out the first section of the url path

---
cascade:
- url: /:sections[1:]/:slugorfilename

URL paths are mostly unchanged

Very few URL paths are changed on the rendered site. This change only affects where the files are placed on the filesystem in the repository, except for a few pages where I had to create sections that were previously missing.

Relative vs absolute links for the manuals section

Relative links and absolute links behave slightly differently after this change; before, relative links could be resolved more or less the same as absolute links (because the internal link to an .md file would be the same as it would be to the rendered .html file (relative to the content directory). Now, relative links to content in the manuals section are prefixed with /manuals, whereas absolute links to these pages point to the rendered page route, e.g. without the /manuals prefix (because that gets stripped out with the url rewrite that we cascade down from the manuals root page).

I don't like this difference much. We currently allow it because we have a very flexible render hook for resolving links. But I think we might want to clean this up at some point, and only use relative paths (/manuals/path/to/file.md) for internal links, not the rendered html link.

Section pages

I have added a number of _index.md files to represent sections. Our previous site didn't have any content on the "section" level, but we had overview pages inside each section. Usually those overview pages were just the _index.md page for that section, but sometimes they weren't.

In some cases, we didn't have an _index.md page for a section. To handle backward compatibility with this content structure, I have added support for "empty" _index.md section pages. This means we get sections without list pages. In this case, the section still appears as an expandable entry in the sidebar, but the seciontitle is not a clickable page/link. Instead, it only lets you expand/collapse. This is achieved using _index.md "stubs" that aren't rendered to disk:

---
title: CLI reference
weight: 10
build:
  render: never
---

Link titles

I have updated titles and added linkTitles to several pages. Now that we do not have a data/toc.yaml file we will populate the sidebar using page titles, and breadcrumbs. We can use linkTitle front matter key to assign a secondary, usually shorter title, for sidebar and breadcrumbs.

Todo

• Update upstream pages, add missing titles
• Double-check redirects

Related PRs

• docs: rename plugins index file and add linkTitle cli#5403
• docs: use front matter title in buildkitd.toml doc moby/buildkit#5294

Follow-up work

• Some sections did not have sections where they should have to match the sidebar structure. To avoid having to deal with restructured files and broken links too much in this PR, this is something I think we should address in a follow-up.

  • Docker Desktop
  • Compose file reference

• There are lots of links that point to redirected pages. Again, this is something we allow for in the current, relaxed render hook. But as with the absolute/relative links issue, I think it's something we should address in a follow-up, and not allow any internal links pointing to redirected content.

[netlify]

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	5c22a72
🔍 Latest deploy log	https://app.netlify.com/sites/docsdocker/deploys/66debef32256a50008db7d86
😎 Deploy Preview	https://deploy-preview-20761--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[aevesdocker]

LGTM, didn't spot any weird behaviour

[aevesdocker]

LGTM and noted the follow-up tasks 👍

[usha-mandya]

LGTM