Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: fix janky rendering of toc on docs.docker.com #5653

Merged
merged 1 commit into from
Nov 28, 2024
Merged

docs: fix janky rendering of toc on docs.docker.com #5653

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/reference/dockerd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -892,7 +892,7 @@ Alternatively, you can set custom locations for CDI specifications using the
When CDI is enabled for a daemon, you can view the configured CDI specification
directories using the `docker info` command.

#### <a name="log-format"></a> Daemon logging format
#### Daemon logging format {#log-format}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we use this approach for all of the CLI reference docs (and use that format to match sections with the options table); is it an issue for those as well?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, there it works because they use a different templating logic.

The default toc rendering uses a recursive template on Hugo's heading fragments, which are parsed out of the markdown file: https://github.com/docker/docs/blob/main/layouts/partials/pagemeta.html

The CLI reference docs are rendered from yaml files, so we can't use the same API. Instead, we construct the toc manually using a page store, and render that: https://github.com/docker/docs/blob/380ca6cc9de0143e462cd36c14f91319de22aece/layouts/_default/cli.html#L197-L224

Funny thing is that the markdown-in-yaml of the CLI reference files also contain the {#syntax} for heading IDs. It's just the source markdown files in these upstream repos that have the <a name=""></a> markup. The empty links are converted to {#syntax} by cli-docs-tool; https://github.com/docker/cli-docs-tool/blob/53293118a80f36cef8740c257aadba0507bdf572/markdown.go#L87-L100

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah! That way, gotcha


The `--log-format` option or "log-format" option in the [daemon configuration file](#daemon-configuration-file)
lets you set the format for logs produced by the daemon. The logging format should
Expand Down Expand Up @@ -1000,7 +1000,7 @@ Example of usage:
}
```

### <a name="feature"></a> Enable feature in the daemon (--feature)
### Enable feature in the daemon (--feature) {#feature}

The `--feature` option lets you enable or disable a feature in the daemon.
This option corresponds with the "features" field in the [daemon.json configuration file](#daemon-configuration-file).
Expand Down
Loading