tree: add new shortcode #1067

assets/css/theme.css

@@ -1762,6 +1762,88 @@ html[dir='rtl'] .expand[open] > .box-label > i.expander-icon {
   font-weight: 500;
 }
 
+/* tree shortcode */
+
+.list-tree ul {
+  list-style-type: none;
+  padding: 0;
+  position: relative;
+  overflow: hidden;
+}
+
+.list-tree > ul {
+  margin-inline-start: -0.5rem;
+}
+
+.list-tree li {
+  color: var(--INTERNAL-MAIN-TEXT-color);
+  margin-bottom: 0;
+  margin-inline-end: 0;
+  margin-inline-start: 9px;
+  margin-top: 0;
+  padding-bottom: 0;
+  padding-inline-end: 12px;
+  padding-inline-start: 20px;
+  padding-top: 0;
+  position: relative;
+}
+
+.list-tree li::before,
+.list-tree li::after {
+  content: '';
+  position: absolute;
+  inset-inline-start: 0;
+}
+
+/* horizontal line on inner list items */
+
+.list-tree li::before {
+  border-top: 2px solid var(--INTERNAL-MAIN-TEXT-color);
+  height: 0;
+  top: 14px;
+  width: 15px;
+}
+
+/* vertical line on list items */
+
+.list-tree li:after {
+  border-left: 2px solid var(--INTERNAL-MAIN-TEXT-color);
+  height: 100%;
+  top: -5px;
+  width: 0px;
+}
+
+/* lower line on list items from the first level because they don't have parents */
+
+.list-tree > ul > li::after {
+  top: 15px;
+}
+
+/* hide line from the last of the first level list items */
+
+.list-tree > ul > li:last-child::after {
+  display: none;
+}
+
+/* hide line from before the Home or starting page or first element	*/
+
+.list-tree > ul > li:first-child::before {
+  display: none;
+}
+
+.list-tree ul:last-child li:last-child:after {
+  height: 20px;
+}
+
+.list-tree i {
+  color: var(--INTERNAL-PRIMARY-color);
+  margin-inline-end: 3px;
+}
+
+.list-tree i.cstyle {
+  color: var(--VARIABLE-BOX-color);
+}
+
 .btn {
   background-color: var(--VARIABLE-BOX-color);
   border-radius: 4px;

docs/content/authoring/markdown.en.md

@@ -438,6 +438,44 @@ Markdown will automatically number each of your items consecutively. This means,
   - [ ] Smell
 {{% /notice %}}
 
+### Tree
+
+{{% badge color="#7dc903" icon="fa-fw fas fa-puzzle-piece" %}}Relearn{{% /badge %}} You can add lists as a tree with configurable icons and colors.
+
+Text can be followed by optional double colons (`::`) to define the icon and another optional double colons to define the icon's color.
+
+More details can be found in the [`tree` shortcode docs](shortcodes/tree).
+
+````md
+```tree
+- home::folder
+  - .config::folder
+  - My Documents::folder::gold
+    - index.html
+    - resume.odt::file-word::#df6f40
+  - Images::folder
+    - pic1.jpg
+    - pic2.jpg::file-image::secondary
+  - Code::folder
+    - home.php::fa-fw fab fa-php::#888cc4
+```
+````
+
+{{% notice style="code" icon="eye" title="Result" %}}
+```tree
+- home::folder
+  - .config::folder
+  - My Documents::folder::gold
+    - index.html
+    - resume.odt::file-word::#df6f40
+  - Images::folder
+    - pic1.jpg
+    - pic2.jpg::file-image::secondary
+  - Code::folder
+    - home.php::fa-fw fab fa-php::#888cc4
+```
+{{% /notice %}}
+
 ### Definitions
 
 {{% badge color="#888cc4" icon="fa-fw fab fa-php" %}}PHP{{% /badge %}} Definition lists are made of terms and definitions of these terms, much like in a dictionary.

docs/content/introduction/releasenotes/7/6.en.md

@@ -12,6 +12,8 @@ weight = -6
 
 ### New
 
+- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The new [`tree` shortcode](shortcodes/tree) displays lists as nicely formatted trees with configurable icon and icon color.
+
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme [supports versioning](configuration/sitemanagement/versioning) now, where you can keep older versions of your site accessible via a version switcher at the top of the menu.
 
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The menu configuration for the main menu area, [introduced in 7.1.0](introduction/releasenotes/7/1), is extended to the non-scrolling menu header area between search box and main scrolling area using the `sidebarheadermenus` option and to the menu footer area using the `sidebarfootermenus` option.

docs/content/shortcodes/tree.en.md

@@ -0,0 +1,84 @@
++++
+categories = ['howto', 'reference']
+description = 'Display a list as a tree'
+title = 'Tree'
++++
+
+The `tree` shortcode displays a list as a tree with configurable icons and colors.
+
+````tree
+- home::folder
+  - .config::folder
+  - My Documents::folder::magic
+    - home.php::fa-fw fab fa-php::#888cc4
+````
+
+## Usage
+
+{{< tabs groupid="shortcode-parameter">}}
+{{% tab title="codefence" %}}
+
+````md
+```tree
+- home::folder
+  - .config::folder
+  - My Documents::folder::magic
+    - home.php::fa-fw fab fa-php::#888cc4
+```
+````
+
+{{% /tab %}}
+{{% tab title="shortcode" %}}
+
+````go
+{{%/* tree */%}}
+- home::folder
+  - .config::folder
+  - My Documents::folder::magic
+    - home.php::fa-fw fab fa-php::#888cc4
+{{%/* /tree */%}}
+````
+
+{{% /tab %}}
+{{% tab title="partial" %}}
+
+````go
+{{ partial "shortcodes/tree.html" (dict
+  "page" .
+  "content" `- home::folder
+  - .config::folder
+  - My Documents::folder::magic
+    - home.php::fa-fw fab fa-php::#888cc4`
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+Codefence syntax is widely available in other Markdown parsers like GitHub and therefore is the recommend syntax for generating portable Markdown.
+
+### Parameter
+
+| Name                  | Default          | Notes       |
+|-----------------------|------------------|-------------|
+| _**&lt;content&gt;**_ | _&lt;empty&gt;_  | Your list as Markdown. |
+
+### Item Syntax
+
+`<TEXT> [ :: <ICON> [ :: <COLOR> ] ]`
+
+Text can be followed by optional double colons (`::`) to define an icon and another optional double colons to define the icon's color.
+
+- **ICON**: [Font Awesome icon name](shortcodes/icon#finding-an-icon) set to the left of the text. If you give a single string, it is selected from Font Awesome's [solid](https://fontawesome.com/icons?d=gallery&s=solid&m=free) icons. If you want to use a different set, you have to give the complete styles after the double colons. See above example for the `home.php`.
+
+- **COLOR**: The [CSS color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) to be used. If not set, the primary color will be used.
+
+  You can also set a **style** value known from other shortcodes.
+
+  - by severity: `caution`, `important`, `info`, `note`, `tip`, `warning`
+  - by brand color: `primary`, `secondary`, `accent`
+  - by color: `blue`, `cyan`, `green`, `grey`, `magenta`, `orange`, `red`
+  - by special color: `default`, `transparent`, `code`
+  - you can also [define your own styles](#defining-own-styles).
+
+  If a **style** and a named HTML color have the same name, the HTML color will be used.

docs/content/shortcodes/tree.pir.md

@@ -0,0 +1,6 @@
++++
+categories = ['howto', 'reference']
+description = 'Display a list as a tree'
+title = 'Tree'
++++
+{{< piratify >}}

layouts/_default/_markup/render-codeblock-tree.html

@@ -0,0 +1,5 @@
+{{- partial "shortcodes/tree.html" (dict
+  "page"       .Page
+  "attributes" .Attributes
+  "content"    .Inner
+) }}

layouts/partials/shortcodes/tree.html

@@ -0,0 +1,8 @@
+{{ $content := .content | .page.RenderString }}
+<div class="list-tree">
+{{- $content = (replaceRE `<li>([^<>:]+)::([\w-]+)::([^<>\n\r\t ]+)` `<li><i class="fa-fw fas fa-$2 cstyle $3" style="color: $3;"></i><span>$1</span>` $content) }}
+{{- $content = (replaceRE `<li>([^<>:]+)::([^<>:]+)::([^<>\n\r\t ]+)` `<li><i class="$2 cstyle $3" style="color: $3;"></i><span>$1</span>` $content) }}
+{{- $content = (replaceRE `<li>([^<>:]+)::([\w-]+)` `<li><i class="fa-fw fas fa-$2"></i><span>$1</span>` $content) }}
+{{- $content = (replaceRE `<li>([^<>:]+)::([^<>\n\r\t ]+)` `<li><i class="$2"></i><span>$1</span>` $content) }}
+{{- $content | safeHTML -}}
+</div>

layouts/partials/version.txt

@@ -1 +1 @@
-7.5.0+14ad8e5292e49a22804d346fa4923ca5e9f3aed8
+7.5.0+9412bd9cd584e6d1df597c337605518632319685

layouts/shortcodes/tree.html

@@ -0,0 +1,5 @@
+{{- $_hugo_config := `{ "version": 1 }` }}
+{{- partial "shortcodes/tree.html" (dict
+  "page"    .Page
+  "content" .Inner
+) }}