Skip to content

Commit 50f7d86

Browse files
dvdksndvdksn
authored
Merge pull request #23960 from dvdksn/improve-markdown-rendering
improve markdown rendering
2 parents 2da917e + 23a6fde commit 50f7d86

26 files changed

Lines changed: 370 additions & 82 deletions

‎Dockerfile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ ARG DOCS_URL="https://docs.docker.com"
5151
ENV HUGO_CACHEDIR="/tmp/hugo_cache"
5252
RUN --mount=type=cache,target=/tmp/hugo_cache \
5353
hugo --gc --minify -e $HUGO_ENV -b $DOCS_URL
54+
RUN ./hack/flatten-markdown.sh public
5455

5556
# lint lints markdown files
5657
FROM ghcr.io/igorshubovych/markdownlint-cli:v0.45.0 AS lint

‎hack/flatten-markdown.sh‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
#!/bin/sh
2+
set -e
3+
4+
# Flatten markdown files from public/path/to/page/index.md to public/path/to/page.md
5+
# This makes markdown output links work correctly
6+
7+
PUBLIC_DIR="${1:-public}"
8+
9+
[ -d "$PUBLIC_DIR" ] || { echo "Error: Directory $PUBLIC_DIR does not exist"; exit 1; }
10+
11+
find "$PUBLIC_DIR" -type f -name 'index.md' | while read -r file; do
12+
# Skip the root index.md
13+
[ "$file" = "$PUBLIC_DIR/index.md" ] && continue
14+
15+
# Get the directory containing index.md
16+
dir="${file%/*}"
17+
18+
# Move index.md to parent directory with directory name
19+
mv "$file" "${dir%/*}/${dir##*/}.md"
20+
done
21+
22+
echo "Flattened markdown files in $PUBLIC_DIR"

‎hack/releaser/cloudfront-lambda-redirects.js‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -52,20 +52,31 @@ exports.handler = (event, context, callback) => {
5252
return
5353
}
5454

55-
// Handle directory requests by appending index.html for requests without file extensions
55+
// Check Accept header for markdown/text requests
56+
const headers = request.headers;
57+
const acceptHeader = headers.accept ? headers.accept[0].value : '';
58+
const wantsMarkdown = acceptHeader.includes('text/markdown') ||
59+
acceptHeader.includes('text/plain');
60+
61+
// Handle directory requests by appending index.html or index.md for requests without file extensions
5662
let uri = request.uri;
5763

5864
// Check if the URI has a dot after the last slash (indicating a filename)
5965
// This is more accurate than just checking the end of the URI
6066
const hasFileExtension = /\.[^/]*$/.test(uri.split('/').pop());
6167

62-
// If it's not a file, treat it as a directory and append index.html
68+
// If it's not a file, treat it as a directory
6369
if (!hasFileExtension) {
64-
// Ensure the URI ends with a slash before appending index.html
70+
// Ensure the URI ends with a slash before appending index file
6571
if (!uri.endsWith("/")) {
6672
uri += "/";
6773
}
68-
uri += "index.html";
74+
// Serve markdown if Accept header requests it, otherwise serve HTML
75+
uri += wantsMarkdown ? "index.md" : "index.html";
76+
request.uri = uri;
77+
} else if (wantsMarkdown && uri.endsWith('.html')) {
78+
// If requesting a specific HTML file but wants markdown, try the .md version
79+
uri = uri.replace(/\.html$/, '.md');
6980
request.uri = uri;
7081
}
7182

‎hugo.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,10 @@ outputs:
9292
section:
9393
- html
9494
- markdown
95+
taxonomy:
96+
- html
97+
term:
98+
- html
9599

96100
languages:
97101
en:

‎layouts/_default/api.markdown.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: {{ .Title }}
3+
url: {{ .Permalink }}
4+
{{- range .Ancestors }}
5+
{{- if and (not .IsHome) .Permalink }}
6+
parent:
7+
title: {{ .Title }}
8+
url: {{ .Permalink }}
9+
{{- break }}
10+
{{- end }}
11+
{{- end }}
12+
{{- if .Ancestors }}
13+
breadcrumbs:
14+
{{- range .Ancestors.Reverse }}
15+
{{- if and (not .IsHome) .Permalink }}
16+
- title: {{ .Title }}
17+
url: {{ .Permalink }}
18+
{{- end }}
19+
{{- end }}
20+
- title: {{ .Title }}
21+
url: {{ .Permalink }}
22+
{{- end }}
23+
{{- with .NextInSection }}
24+
next:
25+
title: {{ .Title }}
26+
url: {{ .Permalink }}
27+
{{- end }}
28+
{{- with .PrevInSection }}
29+
prev:
30+
title: {{ .Title }}
31+
url: {{ .Permalink }}
32+
{{- end }}
33+
{{- $specURL := urls.Parse (printf "/%s%s.yaml" .File.Dir .File.ContentBaseName) }}
34+
openapi_spec: {{ $specURL.String | absURL }}
35+
---
36+
37+
{{ .Content }}
38+
39+
**OpenAPI Specification:** [{{ .Title }} API Spec]({{ $specURL.String | absURL }})
40+
41+
This page provides interactive API documentation. For the machine-readable OpenAPI specification, see the link above.

‎layouts/_default/cli.html‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,12 @@
1010
<div class="flex w-full">
1111
<article class="prose min-w-0 flex-[2_2_0%] max-w-4xl dark:prose-invert">
1212
{{ partial "breadcrumbs.html" . }}
13-
<h1>{{ .Title }}</h1>
13+
<div class="flex items-start justify-between gap-4">
14+
<h1>{{ .Title }}</h1>
15+
<div class="md-dropdown ml-auto mr-4 hidden lg:block">
16+
{{ partial "md-dropdown.html" . }}
17+
</div>
18+
</div>
1419
<div class="overflow-x-auto">
1520
<table>
1621
<tbody>

‎layouts/_default/cli.markdown.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
{{- $data := "" }}
2+
{{- if .Params.datafolder }}
3+
{{- $data = index (index site.Data .Params.datafolder) .Params.datafile }}
4+
{{- else }}
5+
{{- $data = index site.Data .Params.datafile }}
6+
{{- end -}}
7+
---
8+
title: {{ .Title }}
9+
url: {{ .Permalink }}
10+
{{- range .Ancestors }}
11+
{{- if and (not .IsHome) .Permalink }}
12+
parent:
13+
title: {{ .Title }}
14+
url: {{ .Permalink }}
15+
{{- break }}
16+
{{- end }}
17+
{{- end }}
18+
{{- if .Ancestors }}
19+
breadcrumbs:
20+
{{- range .Ancestors.Reverse }}
21+
{{- if and (not .IsHome) .Permalink }}
22+
- title: {{ .Title }}
23+
url: {{ .Permalink }}
24+
{{- end }}
25+
{{- end }}
26+
- title: {{ .Title }}
27+
url: {{ .Permalink }}
28+
{{- end }}
29+
{{- with .NextInSection }}
30+
next:
31+
title: {{ .Title }}
32+
url: {{ .Permalink }}
33+
{{- end }}
34+
{{- with .PrevInSection }}
35+
prev:
36+
title: {{ .Title }}
37+
url: {{ .Permalink }}
38+
{{- end }}
39+
---
40+
41+
{{ with $data.short }}**Description:** {{ . }}{{ end }}
42+
43+
{{ with $data.usage }}**Usage:** `{{ . }}`{{ end }}
44+
45+
{{ with $data.aliases }}{{ $aliases := strings.Replace . (printf "%s, " $.Title) "" }}**Aliases:** {{ range $i, $alias := (strings.Split $aliases ", ") }}{{ if $i }}, {{ end }}`{{ $alias }}`{{ end }}{{ end }}
46+
47+
{{ .Content }}
48+
49+
{{ if $data.deprecated }}> [!WARNING]
50+
> **Deprecated**
51+
>
52+
> This command is deprecated. It may be removed in a future Docker version.
53+
{{ end }}
54+
55+
{{ if or $data.experimental $data.experimentalcli }}> [!NOTE]
56+
> **Experimental**
57+
>
58+
> This command is experimental. Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.
59+
{{ end }}
60+
61+
{{ with $data.kubernetes }}**Orchestrator:** Kubernetes{{ end }}
62+
{{ with $data.swarm }}**Orchestrator:** Swarm{{ end }}
63+
64+
{{ with $data.long }}## Description
65+
66+
{{ . }}
67+
{{ end }}
68+
69+
{{ with $data.options }}{{ $opts := where . "hidden" false }}{{ with $opts }}## Options
70+
71+
| Option | Default | Description |
72+
|--------|---------|-------------|
73+
{{ range . }}{{ $short := .shorthand }}{{ $long := .option }}| {{ with $short }}`-{{ . }}`, {{ end }}`--{{ $long }}` | {{ with .default_value }}{{ $skipDefault := `[],map[],false,0,0s,default,'',""` }}{{ cond (in $skipDefault .) "" (printf "`%s`" .) }}{{ end }} | {{ with .min_api_version }}API {{ . }}+{{ end }}{{ with .deprecated }} **Deprecated**{{ end }}{{ with .experimental }} **experimental (daemon)**{{ end }}{{ with .experimentalcli }} **experimental (CLI)**{{ end }}{{ with .kubernetes }} **Kubernetes**{{ end }}{{ with .swarm }} **Swarm**{{ end }}{{ if .description }} {{ strings.Replace .description "\n" "<br>" }}{{ end }} |
74+
{{ end }}
75+
{{ end }}{{ end }}
76+
77+
{{ with $data.examples }}## Examples
78+
79+
{{ . }}
80+
{{ end }}
81+
82+
{{ if eq .Kind "section" }}## Subcommands
83+
84+
| Command | Description |
85+
|---------|-------------|
86+
{{ range .Pages }}{{ if and .Params.datafolder .Params.datafile }}{{ $subdata := index (index site.Data .Params.datafolder) .Params.datafile }}| [`{{ .Title }}`]({{ .Permalink }}) | {{ $subdata.short }} |
87+
{{ end }}{{ end }}
88+
{{ end }}

‎layouts/_default/list.markdown.md‎

Lines changed: 35 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,36 @@
1-
# {{ .Title }}
1+
---
2+
title: {{ .Title }}
3+
url: {{ .Permalink }}
4+
{{- range .Ancestors }}
5+
{{- if and (not .IsHome) .Permalink }}
6+
parent:
7+
title: {{ .Title }}
8+
url: {{ .Permalink }}
9+
{{- break }}
10+
{{- end }}
11+
{{- end }}
12+
{{- if .Ancestors }}
13+
breadcrumbs:
14+
{{- range .Ancestors.Reverse }}
15+
{{- if and (not .IsHome) .Permalink }}
16+
- title: {{ .Title }}
17+
url: {{ .Permalink }}
18+
{{- end }}
19+
{{- end }}
20+
- title: {{ .Title }}
21+
url: {{ .Permalink }}
22+
{{- end }}
23+
{{- $children := where .Pages "Permalink" "ne" "" }}
24+
{{- if $children }}
25+
children:
26+
{{- range $children }}
27+
- title: {{ .Title }}
28+
url: {{ .Permalink }}
29+
{{- with .Description }}
30+
description: {{ . }}
31+
{{- end }}
32+
{{- end }}
33+
{{- end }}
34+
---
35+
236
{{ .RenderShortcodes }}
3-
{{ range where .Pages "Permalink" "ne" "" }}
4-
- [{{ .Title }}]({{ .Permalink }})
5-
{{ end }}

‎layouts/_default/single.markdown.md‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,35 @@
1-
# {{ .Title }}
1+
---
2+
title: {{ .Title }}
3+
url: {{ .Permalink }}
4+
{{- range .Ancestors }}
5+
{{- if and (not .IsHome) .Permalink }}
6+
parent:
7+
title: {{ .Title }}
8+
url: {{ .Permalink }}
9+
{{- break }}
10+
{{- end }}
11+
{{- end }}
12+
{{- if .Ancestors }}
13+
breadcrumbs:
14+
{{- range .Ancestors.Reverse }}
15+
{{- if and (not .IsHome) .Permalink }}
16+
- title: {{ .Title }}
17+
url: {{ .Permalink }}
18+
{{- end }}
19+
{{- end }}
20+
- title: {{ .Title }}
21+
url: {{ .Permalink }}
22+
{{- end }}
23+
{{- with .NextInSection }}
24+
next:
25+
title: {{ .Title }}
26+
url: {{ .Permalink }}
27+
{{- end }}
28+
{{- with .PrevInSection }}
29+
prev:
30+
title: {{ .Title }}
31+
url: {{ .Permalink }}
32+
{{- end }}
33+
---
34+
235
{{ .RenderShortcodes }}

‎layouts/partials/head.html‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
<meta charset="utf-8" />
22
<meta name="viewport" content="width=device-width, initial-scale=1" />
33
{{ partial "meta.html" . }}
4+
{{- range .AlternativeOutputFormats -}}
5+
<link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink }}" />
6+
{{ end -}}
47
{{ partial "utils/css.html" "-" }}
58
{{- if hugo.IsProduction -}}
69
<script

0 commit comments

Comments
 (0)