From 47ee26e12601f253098c924ca6d874c81b305aab Mon Sep 17 00:00:00 2001 From: Guilherme Gois Date: Wed, 6 Mar 2024 23:32:18 -0300 Subject: [PATCH 1/3] refactor: move scss-docs logic from shortcode to partial - call the partial from the shortcode to not introduces a breaking change --- site/layouts/partials/scss-docs.html | 82 +++++++++++++++++++++++++ site/layouts/shortcodes/scss-docs.html | 83 +------------------------- 2 files changed, 83 insertions(+), 82 deletions(-) create mode 100644 site/layouts/partials/scss-docs.html diff --git a/site/layouts/partials/scss-docs.html b/site/layouts/partials/scss-docs.html new file mode 100644 index 000000000000..39a60282243f --- /dev/null +++ b/site/layouts/partials/scss-docs.html @@ -0,0 +1,82 @@ +{{- /* + Usage: `scss-docs name="name" file="file/_location.scss"` + + Prints everything between `// scss-docs-start "name"` and `// scss-docs-end "name"` + comments in the docs. + + Optional parameters: + * strip-default: Remove the ` !default` flag from variable assignments - default: `true` +*/ -}} + +{{- $name := .Params.name -}} +{{- $file := .Params.file -}} +{{- $strip_default := .Get "strip-default" | default "true" -}} + +{{- /* If any parameters are missing, print an error and exit */ -}} +{{- if or (not $name) (not $file) -}} + {{- errorf "%s: %q: Missing required parameters! Got: name=%q file=%q!" .Position .Name $name $file -}} +{{- else -}} + {{- $capture_start := printf "// scss-docs-start %s\n" $name -}} + {{- $capture_end := printf "// scss-docs-end %s\n" $name -}} + {{- $regex := printf `%s((?:.|\n)*)%s` $capture_start $capture_end -}} + {{- $regex_nested := printf `// scss-docs-.*\n` -}} + + {{- /* + TODO: figure out why we can't do the following and get the first group (the only capturing one)... + $regex := printf `(?:// scss-docs-start %s\n)((?:.|\n)*)(?:\n// scss-docs-end %s)` $name $name + */ -}} + + {{- $match := findRE $regex (readFile $file) -}} + {{- $match = index $match 0 -}} + + {{- if not $match -}} + {{- errorf "%s: %q: Got no matches for name=%q in file=%q!" .Position .Name $name $file -}} + {{- end -}} + + {{- $match = replace $match $capture_start "" -}} + {{- $match = replace $match $capture_end "" -}} + + {{- $match_nested := findRE $regex_nested $match -}} + {{- range $to_remove := $match_nested -}} + {{- $match = replace $match $to_remove "" -}} + {{- end -}} + + {{- if (ne $strip_default "false") -}} + {{- $match = replace $match " !default" "" -}} + {{- end -}} + +
+
+ + {{- $file -}} + +
+ +
+
+ {{- $unindent := 0 -}} + {{- $found := false -}} + {{- $first_line:= index (split $match "\n") 0 -}} + {{- range $char := split $first_line "" -}} + {{- if and (eq $char " ") (not $found) -}} + {{- $unindent = add $unindent 1 -}} + {{- else -}} + {{- $found = true -}} + {{- end -}} + {{- end -}} + {{- $output := "" -}} + {{- if (gt $unindent 0) -}} + {{- $prefix := (strings.Repeat $unindent " ") -}} + {{- range $line := split $match "\n" -}} + {{- $line = strings.TrimPrefix $prefix $line -}} + {{ $output = printf "%s%s\n" $output $line }} + {{- end -}} + {{- $output = chomp $output -}} + {{- else -}} + {{- $output = $match -}} + {{- end -}} + {{- highlight $output "scss" "" -}} +
+{{- end -}} diff --git a/site/layouts/shortcodes/scss-docs.html b/site/layouts/shortcodes/scss-docs.html index 6e7c129f4c29..19fc6db741e9 100644 --- a/site/layouts/shortcodes/scss-docs.html +++ b/site/layouts/shortcodes/scss-docs.html @@ -1,82 +1 @@ -{{- /* - Usage: `scss-docs name="name" file="file/_location.scss"` - - Prints everything between `// scss-docs-start "name"` and `// scss-docs-end "name"` - comments in the docs. - - Optional parameters: - * strip-default: Remove the ` !default` flag from variable assignments - default: `true` -*/ -}} - -{{- $name := .Get "name" -}} -{{- $file := .Get "file" -}} -{{- $strip_default := .Get "strip-default" | default "true" -}} - -{{- /* If any parameters are missing, print an error and exit */ -}} -{{- if or (not $name) (not $file) -}} - {{- errorf "%s: %q: Missing required parameters! Got: name=%q file=%q!" .Position .Name $name $file -}} -{{- else -}} - {{- $capture_start := printf "// scss-docs-start %s\n" $name -}} - {{- $capture_end := printf "// scss-docs-end %s\n" $name -}} - {{- $regex := printf `%s((?:.|\n)*)%s` $capture_start $capture_end -}} - {{- $regex_nested := printf `// scss-docs-.*\n` -}} - - {{- /* - TODO: figure out why we can't do the following and get the first group (the only capturing one)... - $regex := printf `(?:// scss-docs-start %s\n)((?:.|\n)*)(?:\n// scss-docs-end %s)` $name $name - */ -}} - - {{- $match := findRE $regex (readFile $file) -}} - {{- $match = index $match 0 -}} - - {{- if not $match -}} - {{- errorf "%s: %q: Got no matches for name=%q in file=%q!" .Position .Name $name $file -}} - {{- end -}} - - {{- $match = replace $match $capture_start "" -}} - {{- $match = replace $match $capture_end "" -}} - - {{- $match_nested := findRE $regex_nested $match -}} - {{- range $to_remove := $match_nested -}} - {{- $match = replace $match $to_remove "" -}} - {{- end -}} - - {{- if (ne $strip_default "false") -}} - {{- $match = replace $match " !default" "" -}} - {{- end -}} - -
-
- - {{- $file -}} - -
- -
-
- {{- $unindent := 0 -}} - {{- $found := false -}} - {{- $first_line:= index (split $match "\n") 0 -}} - {{- range $char := split $first_line "" -}} - {{- if and (eq $char " ") (not $found) -}} - {{- $unindent = add $unindent 1 -}} - {{- else -}} - {{- $found = true -}} - {{- end -}} - {{- end -}} - {{- $output := "" -}} - {{- if (gt $unindent 0) -}} - {{- $prefix := (strings.Repeat $unindent " ") -}} - {{- range $line := split $match "\n" -}} - {{- $line = strings.TrimPrefix $prefix $line -}} - {{ $output = printf "%s%s\n" $output $line }} - {{- end -}} - {{- $output = chomp $output -}} - {{- else -}} - {{- $output = $match -}} - {{- end -}} - {{- highlight $output "scss" "" -}} -
-{{- end -}} +{{- partial "scss-docs" . }} From 391591467a94e54160bf58c588ea895fa5b80d19 Mon Sep 17 00:00:00 2001 From: Guilherme Gois Date: Wed, 6 Mar 2024 23:34:55 -0300 Subject: [PATCH 2/3] feat: allow named parameter in docsref shortcode --- site/layouts/shortcodes/docsref.html | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/site/layouts/shortcodes/docsref.html b/site/layouts/shortcodes/docsref.html index 06523d859d06..49ee6e625a7d 100644 --- a/site/layouts/shortcodes/docsref.html +++ b/site/layouts/shortcodes/docsref.html @@ -1,2 +1,9 @@ -{{- $pageToReference := path.Join "docs" $.Site.Params.docs_version (.Get 0) -}} +{{- $urlPath := .Get "urlPath" -}} + +{{- if and (not $urlPath) (index .Params 0) -}} + {{- $urlPath = index .Params 0 -}} +{{- end -}} + +{{- $pageToReference := path.Join "docs" $.Site.Params.docs_version $urlPath -}} + {{- relref . $pageToReference | relURL -}} From 7640243ceceaaef83af7353df97cb8186fe7b5ca Mon Sep 17 00:00:00 2001 From: Guilherme Gois Date: Wed, 6 Mar 2024 23:36:13 -0300 Subject: [PATCH 3/3] feat: create sass-utilities-api-section shortcode - use it in the Overflow doc as example --- site/content/docs/5.3/utilities/overflow.md | 8 +++----- site/layouts/shortcodes/sass-utilities-api-section.html | 7 +++++++ 2 files changed, 10 insertions(+), 5 deletions(-) create mode 100644 site/layouts/shortcodes/sass-utilities-api-section.html diff --git a/site/content/docs/5.3/utilities/overflow.md b/site/content/docs/5.3/utilities/overflow.md index 9c8573c3332c..e9898ebc37e2 100644 --- a/site/content/docs/5.3/utilities/overflow.md +++ b/site/content/docs/5.3/utilities/overflow.md @@ -92,8 +92,6 @@ Using Sass variables, you may customize the overflow utilities by changing the ` ## CSS -### Sass utilities API - -Overflow utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}}) - -{{< scss-docs name="utils-overflow" file="scss/_utilities.scss" >}} +{{< sass-utilities-api-section title="Overflow" name="utils-overflow" file="scss/_utilities.scss" >}} + {{% docsref urlPath="/utilities/api#using-the-api/" %}} +{{< /sass-utilities-api-section >}} diff --git a/site/layouts/shortcodes/sass-utilities-api-section.html b/site/layouts/shortcodes/sass-utilities-api-section.html new file mode 100644 index 000000000000..bb3a6c69703a --- /dev/null +++ b/site/layouts/shortcodes/sass-utilities-api-section.html @@ -0,0 +1,7 @@ +

Sass utilities API

+ +

+ {{ index .Params.title }} utilities are declared in our utilities API in scss/_utilities.scss. Learn how to use the utilities API. +

+ +{{- partial "scss-docs" . -}}